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Intrinsics and Widgets 



1 



The X Toolkit Intrinsics and a widget set make up the X Toolkit. The X Toolkit Intrinsics 
provide the base mechanisms necessary to build a wide variety of widget sets and 
application environments. Because the X Toolkit Intrinsics mask implementation details 
from the widget and application programmer, the widgets and the application 
environments built with them are fully extensible and support independently developed 
new or extended components. By following a small set of conventions, widget 
programmers can extend their widget sets in new ways and can have these extensions 
function smoothly with the existing facilities. 

The X Toolkit Intrinsics is a library package layered on top of Xlib. As such, the X 
Toolkit Intrinsics provide mechanisms (functions and structures) for extending the basic 
programming abstractions provided by the X Window System. By providing mechanisms 
for intercomponent and intracomponent interactions, the X Toolkit Intrinsics provide the 
next layer of functionality from which the widget sets are built. 

Figure 1-1 illustrates this extended three-tiered X programming environment. 
+ + 
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A typical X Toolkit application is most likely to be a client of a given widget set, a subset of 
the X Toolkit Intrinsics functions, and a smaller set of Xlib functions. This is illustrated by 
a left-to-right viewing of Figure 1-1. At the same time, a widget set is a client of both the 
X Toolkit Intrinsics and Xlib, and the X Toolkit Intrinsics are a client of Xlib only. This is 
illustrated by a top-to-bottom viewing of Figure 1-1. 

For the application programmer, the X Toolkit provides: 

• A consistent interface (widget set) for writing applications 

• A small set of X Toolkit Intrinsics mechanisms that also are used in writing 
applications 

For the widget programmer, the X Toolkit provides: 

• A set of X Toolkit Intrinsics mechanisms for building widgets 

• An architectural model for constructing and composing widgets 

• A consistent interface (widget set) for programming 

To the extent possible, the X Toolkit is policy free. The application environment, not the X 
Toolkit, defines, implements, and enforces: 

• Policy 

• Consistency 

• Style 

Each individual widget implementation defines its own policy. The X Toolkit design allows 
for the development of radically differing widget implementations. 



1.1 Terminology 

In addition to the terms already defined for X programming (see Programming with Xlib ), 
the following terms are specific to the X Toolkit Intrinsics and used throughout this book. 

Application programmer 

A programmer who uses the X Toolkit to produce an application user interface. 

Class 

The' general group to which a specific object belongs. 
Client 

A function that uses a widget in an application or for composing other widgets. 
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Instance 

A specific widget object as opposed to a general widget class. 
Method 

The functions or procedures that a widget class implements. 

Name 

The name that is specific to an instance of a widget for a given client. 
Object 

A software data abstraction consisting of private data and private and public 
functions that operate on the private data. Users of the abstraction can interact with 
the object only through calls to the object's public functions. In the X Toolkit, some 
of the object's public functions are called directly by the application, while others are 
called indirectly when the application calls the common X Toolkit Intrinsics 
functions. In general, if a function is common to all widgets, an application uses a 
single Intrinsic function to invoke the function for all types of widgets. If a function 
is unique to a single widget type, the widget exports the function as another "Xt" 
function. 

Resource 

A named piece of data in a widget that can be set by a client, by an application, or by 
user defaults. 

User 

A person interacting with a workstation. 
Widget 

An object providing a user-interface abstraction (for example, a Scrollbar widget). 
Widget class 

The general group to which a specific widget belongs, otherwise known as the type of 
the widget. 

Widget programmer 

A programmer who adds new widgets to the X Toolkit. 



1.2 Intrinsics 

The X Toolkit Intrinsics provide the base mechanisms (functions and structures) that 
simplify the design of application user interfaces. In addition, it assists widget and 
application programmers by providing a commonly used set of underlying user-interface 
functions to manage: 
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• Toolkit initialization Widgets 

• Memory 

• Window, file, and timer events 

• Widget geometry 

• Input focus 

• Selections 

• Resources and resource conversion 

• Translation of events 

• Graphics contexts 

• Pixmaps 

• Errors and warnings 

Although all X Toolkit Intrinsics mechanisms are primarily intended for use by widget 
programmers, some are also intended for use by application programmers. The 
architectural model for the X Toolkit Intrinsics lets the widget programmer create new 
widgets by using the supplied mechanisms and/or by combining existing widgets. 
Therefore, an application interface layers built with the X Toolkit Intrinsics will provide a 
coordinated set of widgets and composition policies. While some of the widgets that are 
built with the X Toolkit Intrinsics are common across a number of application domains, 
others are restricted to a specific application domain. 

The X Toolkit Intrinsics are based on an architectural model that also is flexible enough to 
accommodate a variety of different application interface layers. In addition, the supplied 
set of X Toolkit Intrinsics mechanisms are: 

• Functionally complete and policy free 

• Stylistically and functionally consistent with the X Window System primitives 

• Portable across languages, computer architectures, and operating systems 

Applications that use the X Toolkit Intrinsics mechanisms must include the following 
header files: 

• <X11/Intrinsic . h> 

. <Xll/StringDefs.h> 
In addition, they may also include: 

• <Xll/Xatoms .h> 
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• <X11/Shell.h> 

Finally, widget implementations should include: 

• <Xll/IntrinsicP.h> instead of <X11/Intrinsic .h>. 

The applications should also include the additional headers for each widget class that they 
are to use (for example, < Xll/Label . h > or < Xll/Scroll . h >). The X Toolkit 
Intrinsics object library file is named libXt . a and is usually referenced as -lXt. 



1.3 Widgets 

The fundamental abstraction and data type of the X Toolkit is the widget, which is a 
combination of an X window and its associated semantics and which is dynamically 
allocated and contains state information. Logically, a widget is a rectangle with associated 
input/output semantics. Some widgets display information (for example, text or graphics), 
and others are merely containers for other widgets (for example, a menu box). Some 
widgets are output-only and do not react to pointer or keyboard input, and others change 
their display in response to input and can invoke functions that an application has attached 
to them. 

Every widget belongs to exactly one widget class that is statically allocated and initialized 
and that contains the operations allowable on widgets of that class. Logically, a widget 
class is the procedures and data that is associated with all widgets belonging to that class. 
These procedures and data can be inherited by subclasses. Physically, a widget class is a 
pointer to a structure. The contents of this structure are constant for all widgets of the 
widget class but will vary from class to class. (Here, constant means the class structure is 
initialized at compile-time and never changed, except for a one-time class initialization and 
in-place compilation of resource lists, which takes place when the first widget of the class 
or subclass is created.) For further information, see Section 2.4. 

The organization of the declarations and code for a new widget class between a public .h 
file, a private .h file, and the implementation .c file is described in Section 1.4. The 
predefined widget classes adhere to these conventions. 

A widget instance is composed of two parts: 

• A data structure that contains instance-specific values 

• A class structure that contains information that is applicable to all widgets of that 
class 

Much of the input/output of a widget (for example, fonts, colors, sizes, border widths, and 
so on) is customizable by users. 

The next three sections discuss the base widget classes: 
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• Core widgets 

• Composite widgets 

• Constraint widgets 

The chapter ends with a discussion of widget classing. 

1.3.1 Core Widgets 

The Core widget contains the definitions of fields common to all widgets. All widgets 
are subclasses of Core, which is defined by the CoreClassPart and CorePart 
structures. 

CoreClassPart Structure 

The common fields for all widget classes are defined in the CoreClassPart structure: 

typedef struct { 

WidgetClass superclass; See Section 1.4 

String class_name; See Section 1.4 

Cardinal widget_size; See Section 2.4 

XtProc class_initialize; See Section 1.4 

XtWidgetClassProc class_part_initialize;See Section 1.4 

Boolean class_inited; See Section 1.4 

XtlnitProc initialize; See Section 2.4 

XtArgsProc initialize_hook; See Section 2.4 

XtRealizeProc realize; See Section 2.4 

XtActionList actions; See Chapter 10 

Cardinal num_actions; See Chapter 10 

XtResourceList resources; See Chapter 9 

Cardinal num_resources ; See Chapter 9 

XrmClass xrm_class; Private to resource manager 

Boolean compress_motion; See Section 7.9.1 

Boolean compress_exposure; See Section 7.9.3 

Boolean compress_enterleave; See Section 7.9.2 

Boolean visible_interest; See Section 7.10 

XtWidgetProc destroy; See Section 2.7 

XtWidgetProc resize; See Chapter 6 

XtExposeProc expose; See Section 7.10 

XtSetValuesFunc set_values; See Section 9.7 

XtArgsFunc set_values_hook; See Section 9.7 

XtAlmostProc set_values_almost;See Section 9.7 

XtArgsProc get_values_hook ; See Section 9.7 

XtAcceptFocusProc accept_focus;See Section 7.3 

XtVersionType version; See Section 1.4 

_XtOffsetList callback_private; Private to callbacks 

String tm_table; See Chapter 10 

XtGeometryHandler query_geometry;See Chapter 6 

XtStringProc display_accelerator;See Chapter 10 

caddr_t extension; See Section 1.4 

} CoreClassPart; 
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All widget classes have the core class fields as their first component. The prototypical 
WidgetClass is defined with only this set of fields. Various routines can cast widget 
class pointers, as needed, to specific widget class types, for example: 

typedef struct { 

CoreClassPart core_class; 
} WidgetClassRec, *WidgetClass; 

The predefined class record and pointer for WidgetClassRec are: 

extern WidgetClassRec WidgetClassRec; 
extern WidgetClass widgetClass; 

The opaque types Widget and WidgetClass and the opaque variable 
widgetClass are defined for generic actions on widgets. 

CorePart Structure 

The common fields for all widget instances are defined in the CorePart structure: 
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typedef struct _CorePart { 
Widget self; 

WidgetClass widget_class ; 
Widget parent; 
XrmName xrm_name; 
Boolean being_destroyed; 



See Section 1.4 

See Section 1.4 

Private to resource manager 

See Section 2.7 



XtCallbackList destroy callbacks; See Section 2.7 



caddr_t constraints; 
Position x; 
Position y; 
Dimension width; 
Dimension height; 
Dimension border_width; 
Boolean managed; 
Boolean sensitive; 
Boolean ancestor_sensitive ; 
XtEventTable event_table ; 
XtTMRec tm; 



See Section 3.7 

See Chapter 6 

See Chapter 6 

See Chapter 6 

See Chapter 6 

See Chapter 6 

See Chapter 3 

See Section 7.7 

See Section 7.7 

Private to event manager 

Private to translation manager 



XtTranslations accelerators; 


See 


Chapter 
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Pixel border_jpixel; 


See 


Section 


2. 


6 


Pixmap border_pixmap ; 


See 


Section 


2. 


6 


WidgetList popup_list; 


See 


Chapter 


5 




Cardinal numjpopups; 


See 


Chapter 


5 




String name; 


See 


Chapter 
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Screen *screen; 


See 


Section 


2. 
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Colormap colormap; 


See 


Section 


2. 
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Window window; 


See 


Section 


2. 
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Cardinal depth; 


See 


Section 


2. 
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Pixel background_pixel; 


See 


Section 


2. 
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Pixmap background_pixmap; 


See 


Section 


2. 
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Boolean visible; 


See 


Section 


7. 
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Boolean mapped_when_managed; 


See 


Chapter 


3 





} CorePart; 



All widget instances have the core fields as their first component. The prototypical type 
Widget is defined with only this set of fields. Various routines can cast widget pointers, 
as needed, to specific widget types; for example: 

typedef struct { 

CorePart core; 
} WidgetRec, *Widget; 

CorePart Default Values 

The default values for the core fields, which are filled in by the Core resource list and 
the Core initialize procedure, are: 
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Field Default Value 



self Address of the widget structure (may not be changed) 

widget_class widget_class argument to XtCreateWidget (may 

not be changed) 

parent parent argument to XtCreateWidget (may not be 

changed) 

xrm_name Encoded name argument to XtCreateWidget (may 

not be changed) 

being_destroyed Parent's being_destroyed value 

destroy_callbacks NULL 

constraints NULL 

x 0 

y 0 

width 0 

height 0 

border_width 1 

managed False 

sensitive True 

ancestor_sensitive Bitwise AND of parent's sensitive & ancestorjsensitive 

event_table Initialized by the event manager 

tm Initialized by the translation manager 

accelerators NULL 

border_pixel XtDefaultFo re ground 

border_pixmap NULL 

popup_list NULL 

num_popups 0 

name name argument to XtCreateWidget (may not be 

changed) 

screen Parent's screen, top-level widget gets it from display 

specifier (may not be changed) 

colormap Default color map for the screen 

window NULL 

depth Parent's depth, top-level widget gets root window depth 

background_pixel XtDe f aul tBackgr ound 

background_pixmap NULL 

visible True 

map_when_managed True 
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1.3.2 Composite Widgets 



Composite widgets are a subclass of the Core widget (see Chapter 3) are intended to 
be containers for other widgets, and are defined by the C omp ositeClassPart and 
Compos itePart structures. 



CompositeClassPart Structure 

In addition to the Core widget class fields, 
fields: 



Composite widgets have the following class 



typedef struct { 

XtGeometryHandler geometry_manager ; See Chapter 6 

XtWidgetProc change_managed; See Chapter 3 

XtWidgetProc insert_child; See Chapter 3 

XtWidgetProc delete_child; See Chapter 3 

caddr_t extension; See Section 1.4 

} CompositeClassPart; 



Composite widget classes have the composite fields immediately following the core 
fields: 

typedef struct { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

} CompositeClassRec, *CompositeWidgetClass ; 

The predefined class record and pointer for CompositeClassRec are: 

extern CompositeClassRec CompositeClassRec; 
extern WidgetClass compositeWidgetClass; 



The opaque types Compos iteWidget and CompositeWidgetClass and the 
opaque variable compos i teWidgetClass are defined for generic operations on 
widgets that are a subclass of Compos iteWidget. 

CompositePart Structure 

In addition to the CorePart fields, Composite widgets have the following fields 
defined in the CompositePart structure: 



typedef struct { 

WidgetList children; See Section 1.4 

Cardinal num_children; See Section 1.4 

Cardinal num_slots ; See Chapter 3 

XtOrderProc insert_position; See Section 2.4 

} CompositePart; 
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Composite widgets have the composite fields immediately following the core fields: 



typedef struct { 

CorePart core; 

CompositePart composite; 
} CompositeRec, *CompositeWidget; 



CompositePart Default Values 

The default values for the composite fields, which are filled in by the Compos ite 
resource list and the Composite initialize procedure, are: 



Field 


Default Value 


children 


NULL 


num children 


0 


num_slots 


0 


insertjposition 


Internal function InsertAtEnd 



1 .3.3 Constraint Widgets 

Constraint widgets are a subclass of the Composite widget (see Section 3.7) that 
maintain additional state data for each child, for example, client-defined constraints on the 
child's geometry. They are defined by the ConstraintClassPart and 
ConstraintPart structures. 

ConstraintClassPart Structure 

In addition to the Composite class fields, Constraint widgets have the following 
class fields: 



typedef struct { 

XtResourceList resources; See Section 3.7 

Cardinal num_resources; See Section 3.7 

Cardinal constraint_size; See Section 3.7 

XtlnitProc initialize; See Section 3.7 

XtWidgetProc destroy; See Section 3.7 

XtSetValuesFunc set_values; See Section 3.7 

caddr_t extension; See Section 1.4 

} ConstraintClassPart; 



Constraint widget classes have the constraint fields immediately following the 
composite fields: 
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typedef struct { 

CoreClassPart core_class; 

CompositeClassPart compos ite_c lass ; 

ConstraintClassPart constraint_class ; 

} ConstraintClassRec, *ConstraintWidgetClass ; 

The predefined class record and pointer for ConstraintClassRec are: 

extern ConstraintClassRec ConstraintClassRec; 
extern WidgetClass constraintWidgetClass; 

The opaque types Cons traintWidget and ConstraintWidgetClass and the 
opaque variable constraintWidgetClass are defined for generic operations on 
widgets that are a subclass of ConstraintWidgetClass . 

ConstraintPart Structure 

In addition to the Compos itePart fields, Constraint widgets have the following 
fields defined in the ConstraintPart structure: 

typedef struct { int empty; } ConstraintPart; 

Constraint widgets have the constraint fields immediately following the composite 
fields: 

typedef struct { 

CorePart core; 

CompositePart composite; 

ConstraintPart constraint; 
} ConstraintRec , *ConstraintWidget; 



1.4 Widget Classing 

The widget_class field of a widget points to its widget class structure, which contains 
information that is constant across all widgets of that class. As a consequence, widget 
classes usually do not implement directly callable procedures; rather, they implement 
procedures that are available through their widget class structure. These methods are 
invoked by generic procedures that envelop common actions around the procedures 
implemented by the widget class. Such procedures are applicable to all widgets of that 
class and also to widgets that are subclasses of that class. 
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All widget classes are a subclass of Core and can be subclassed further. Subclassing 
reduces the amount of code and declarations you write to make a new widget class that is 
similar to an existing class. For example, you do not have to describe every resource your 
widget uses in an XtResourceList. Instead, you describe only the resources your 
widget has that its superclass does not. Subclasses usually inherit many of their 
superclass's procedures (for example, the expose procedure or geometry handler). 

Subclassing, however, can be taken too far. If you create a subclass that inherits none of 
the procedures of its superclass, you should consider whether or not you have chosen the 
most appropriate superclass. 

To make good use of subclassing, widget declarations and naming conventions are highly 
stylized. A widget consists of three files: 

• A public .h file that is used by client widgets or applications 

• A private .h file that is used by widgets that are subclasses of the widget 

• A .c file that implements the widget class 



1 .4.1 Widget Naming Conventions 

The X Toolkit Intrinsics provide a vehicle by which programmers can create new widgets 
and organize a collection of widgets into an application. To ensure that applications need 
not deal with as many styles of capitalization and spelling as the number of widget classes it 
uses, the following guidelines should be followed when writing new widgets: 

• Use the X naming conventions that are applicable. For example, a record 
component name is all lowercase and uses underscores (_) for compound words (for 
example, background_pixmap). Type and procedure names start with uppercase and 
use capitalization for compound words (for example, ArgList or 
XtSetValues). 

• A resource name string is spelled identically to the field name except that compound 
names use capitalization rather than underscore. To let the compiler catch spelling 
errors, each resource name should have a macro definition prefixed with XtN. For 
example, the background_pixmap field has the corresponding resource name 
identifier XtNbackgroundPixmap, which is defined as the string 
"backgroundPixmap". Many predefined names are listed in 

< XI 1/S t r ingDe f s . h > . Before you invent a new name, you should make sure 
that your proposed name is not already defined or that there is not already a name 
that you can use. 
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• A resource class string starts with a capital letter and uses capitalization for 
compound names (for example/'BorderWidth"). Each resource class string should 
have a macro definition prefixed with XtC (for example, XtCBorderWidth). 

• A resource representation string is spelled identically to the type name (for example, 
"TranslationTable"). Each representation string should have a macro definition 
prefixed with XtR (for example, XtRTranslationTable). 

• New widget classes start with a capital and use uppercase for compound words. 
Given a new class name AbcXyz you should derive several names: 

• Partial widget instance structure name AbcXyzPart 

• Complete widget instance structure names AbcXyzRec and AbcXyzRec 

• Widget instance pointer type name AbcXyzWidget 

• Partial class structure name AbcXyzClassPart 

• Complete class structure names AbcXyzClassRec and _AbcXyzClassRec 

• Class structure variable abcXyzClassRec 

• Class pointer variable abcXyzWidgetClass 

• Action procedures available to translation specifications should follow the same 
naming conventions as procedures. That is, they start with a capital letter and 
compound names use uppercase (for example, "Highlight" and "NotifyClient"). 

1.4.2 Widget Subclassing in Public .h Files 

The public .h file for a widget class is imported by clients and contains: 

• A reference to the public .h files for the superclass 

• The names and classes of the new resources that this widget adds to its superclass 

• The class record pointer that you use to create widget instances 

• The C type that you use to declare widget instances of this class 

• Entry points for new class methods 

For example, the following is the public .h file for a possible implementation of a Label 
widget: 

#ifndef LABEL_H 
#define LABEL H 
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/* New resources */ 

#define XtNjustify "justify" 

#def ine XtNforeground "foreground" 

#define XtNlabel "label" 

#define XtNfont "font" 

#def ine XtNinternalWidth"internalWidth" 

#def ine XtNinternalHeighfinternalHeight" 

/* Class record pointer */ 

extern WidgetClass labelWidgetClass ; 

/* C Widget type definition */ 

typedef struct _LabelRec *LabelWidget; 

/* New class method entry points */ 
extern void Label SetText(); 

/* Widget w */ 

/* String text */ 

extern String Label GetTextO; 
/* Widget w */ 

#endif LABEL_H 

The conditional inclusion of the text allows the application to include header files for 
different widgets without being concerned that they already may be included as a 
superclass of another widget. 

To accommodate operating systems with file name length restrictions, the name of the 
public .h file is the first ten characters of the widget class. For example, the public .h file 
for the Constraint widget is Constraint .h. 

1 .4.3 Widget Subclassing in Private .h Files 

The private .h file for a widget is imported by widget classes that are subclasses of the 
widget and contains: 

• A reference to the public .h file for the class 

• A reference to the private .h file for the superclass 

• The new fields that the widget instance adds to its superclass's widget structure 

• The complete widget instance structure for this widget 

• The new fields that this widget class adds to its superclass's Constraint structure 
if the widget is a subclass of Constraint 

• The complete Constraint structure if the widget is a subclass of Constraint 

• The new fields that this widget class adds to its superclass's widget class structure 
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• The complete widget class structure for this widget 

• The name of a constant of the generic widget class structure 

-n inherit procedure for subclasses that wish to inherit a superclass operation for 
each new procedure in the widget class structure 

For example, the following is the private .h file for a possible Label widget: 

#ifndef LABELP_H 
#define LABELP_H 

#include <X11/Label.h> 

/* New fields for the Label widget record */ 

typedef struct { 

/* Settable resources */ 

Pixel foreground; 

XFontStruct *font; 

String label; /* text to display */ 

Xt Justify justify; 

Dimension internal_width; /* # of pixels horizontal border */ 

Dimension internal_height; /* # of pixels vertical border */ 

/* Data derived from resources */ 

GC normal_GC; 

GC gray_GC; 

Pixmap gray_pixmap; 

Position label_x; 

Position label_y; 

Dimension label_width; 

Dimension label_height; 

Cardinal label_len; 

Boolean display_sensitive; 
} LabelPart; 



/* Full instance record declaration */ 
typedef struct _LabelRec { 

CorePart core; 

LabelPart label; 
} LabeLRec; 

/* Types for label class methods */ 
typedef void (*LabelSetTextProc ) ( ) ; 

/* Widget w */ 

/* String text */ 

typedef String (*LabelGetTextProc ) ( ) ; 
/* Widget w */ 
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/* New fields for the Label widget class record */ 
typedef struct { 

LabelSetTextProc set_text; 

LabelGetTextProc get_text; 

caddr_t extension; 
} LabelClassPart; 

/* Full class record declaration */ 
typedef struct _LabelClassRec { 

CoreClassPart core_class; 

LabelClassPart label_class; 
} LabelClassRec; 

/* Class record variable */ 

extern LabelClassRec labelClassRec ; 

#define LabelInheritSetText( (LabelSetTextProc )_XtInherit) 
#define LabelInheritGetText( (LabelGetTextProc )_XtInherit) 
#endif LABELP_H 



To accommodate operating systems with file name length restrictions, the name of the 
private .h file is the first nine characters of the widget class followed by a capital P. For 
example, the private .h file for the Constraint widget is Cons trainP . h. 

1.4.4 Widget Subclassing in .c Files 

The x file for a widget contains the structure initializer for the class record variable, which 
contains the following parts: 

• Class information (for example, superclass, class_name, widget_size, class_initialize, 
and class_inited) 

• Data constants (for example, resources and num_resources, actions and 
num_actions, visible_interest, compressmotion, compress_exposure, and version) 

• Widget operations (for example, initialize, realize, destroy, resize, expose, set_values, 
accept_focus, and any operations specific to the widget) 

The superclass field points to the superclass WidgetClass record. For direct 
subclasses of the generic core widget, superclass should be initialized to the address of the 
widgetClassRec structure. The superclass is used for class chaining operations and for 
inheriting or enveloping a superclass's operations. (See Sections 1.4.7, 1.4.9, and 1.4.10). 

The class_name field contains the text name for this class (used by the resource manager). 
For example, the Label widget has the string "Label". More than one widget class can 
share the same text class name. 

The widget_size field is the size of the corresponding widget structure (not the size of the 
Class structure). 
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The version field indicates the toolkit version number and is used for run-time consistency 
checking of the X Toolkit and widgets in an application. Widget writers must set it to the 
symbolic value XtVersion in the widget class initialization. Those widget writers who 
know that their widgets are backwards compatible with previous versions of the X Toolkit 
Intrinsics can put the special value XtVersionDontCheck in the version field to turn 
off version checking for those widgets. 

The extension field is for future upwards compatibility. If you add additional fields to class 
parts, all subclass structure layouts change, requiring complete recompilation. To allow 
clients to avoid recompilation, an extension field at the end of each class part can point to 
a record that contains any additional class information required. 

All other fields are described in their respective sections. 

The following is an abbreviated version of the ".c" file for the Label widget. (The 
resources table is described in the Chapter 9.) 

/* Resources specific to Label */ 
#define XtRJustify "Justify" 
static XtResource resources [] = { 

{XtNforeground, XtCForeground, XtRPixel, sizeof (Pixel) , 

XtOffset(LabelWidget, label. foreground) , XtRString, XtDef aultForeground} , 
{XtNfont, XtCFont, XtRFontStruct, sizeof (XFontStruct *), 

XtOffset(LabelWidget, label. font) .XtRString, XtDef aultFont} , 
{XtNlabel, XtCLabel, XtRString, sizeof (String) , 

XtOffset(LabelWidget, label. label) , XtRString, NULL}, 



/* Forward declarations of procedures */ 

static void Classlnitialize( ) ; 

static void Initialize( ) ; 

static void RealizeO; 

static void SetTextO; 

static void GetTextO; 



/* Class record constant */ 
LabelClassRec labelClassRec = { 



} 



{ 



/* core_class fields */ 
/* superclass */ 
/* class_name */ 
/* widget_size */ 
/* class initialize 



(WidgetClass) &widgetClassRec , 
"Label" , 

sizeof (LabelRec ) , 
*/ClassInitialize , 
*/NULL, 
False, 



/* class_part_initialize 



/* class_inited */ 
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}, 
{ 



/* initialize */ 
/* initialize_hook */ 
/* realize */ 
/* actions */ 
/* num_actions */ 
/* resources */ 
/* num_resources */ 
/* xrm_class */ 
/* compress_motion */ 
/* compress_exposure 
/* compress_enterleave 
/* visible_interest 
/* destroy */ 
/* resize */ 
/* expose */ 
/* set_values */ 
/* set_values_hook */ 
/* set_values_almost 
/* get_values_hook */ 
/* accept_focus */ 
/* version */ 
/* callback_of f sets 
/* tm_table */ 
/* query_geometry */ 
/* display_accelerator 
/* extension */ 



/* Label_class fields 
/* get_text */ 
/* set_text */ 
/* extension */ 



Initialize, 

NULL, 

Realize, 

NULL, 

0, 

resources , 

XtNumber( resources ) , 

NULLQUARK, 

True, 

*/True, 

*/True, 

*/False, 

NULL, 

Resize, 

Redisplay, 

SetValues , 

NULL, 

*/XtInheritSetValuesAlmost , 

NULL, 

NULL, 

XtVersion, 
*/NULL , 
NULL, 

Xtlnher itQueryGeometry , 

*/NULL , 

NULL 



GetText, 
SetText, 
NULL 



}; 



/* Class record pointer */ 

WidgetClass labelWidgetClass = (WidgetClass ) &labelClassRec; 

/* New method access routines */ 
void Label SetText(w, text) 

Widget w; 

String text; 

{ 

Label WidgetClass lwc = (Label WidgetClass )XtClass (w) ; 
XtCheckSubclass(w, labelWidgetClass, NULL); 
*(lwc->label_class . set_text) (w, text) 

} 

/* Private procedures */ 



Intrinsics and Widgets 1-19 



1 .4.5 Widget Class and Superclass Look Up 

To obtain the class of a widget, use XtClass . 

WidgetClass XtClass (w) 
Widget w; 

w Specifies the widget. 

The XtClass function returns a pointer to the widget's class structure. 
To obtain the superclass of a widget, use XtSuperclass. 

WidgetClass XtSuperclass (H>) 
Widget W; 

w Specifies the widget. 

The XtSuperclass function returns a pointer to the widget's superclass class structure. 

1 .4.6 Widget Subclass Verification 

To check the subclass that a widget belongs to, use Xtls Subclass . 

Boolean XtlsSubclass (w, widget_class ) 
Widget w; 

WidgetClass widget_class ; 

w Specifies the widget. 

widget_class Specifies the widget class to test against. 

The XtlsSubclass function returns True if the class of the specified widget is equal 
to or is a subclass of the specified widget class. The specified widget can be any number of 
subclasses down the chain and need not be an immediate subclass of the specified widget 
class. Composite widgets that need to restrict the class of the items they contain can use 
XtlsSubclass to find out if a widget belongs to the desired class of objects. 

To check the subclass that a widget belongs to and generate a debugging error message, 
use XtCheckSubclass. 

void XtCheckSubclass (w, widget _class , message) 
Widget W; 

WidgetClass widget _class; 
String message; 
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message 



w 



widget_class 



Specifies the widget. 

Specifies the widget class to test against. 

Specifies the message that is to be used. 



The XtCheckSubclass macro determines if the class of the specified widget is equal 
to or is a subclass of the specified widget class. The widget can be any number of 
subclasses down the chain and need not be an immediate subclass of the specified widget 
class. If the specified widget is not a subclass, XtCheckSubclass constructs an error 
message from the supplied message, the widget's actual class, and the expected class and 
calls XtErrorMsg. XtCheckSubclass should be used at the entry point of 
exported routines to ensure that the client has passed in a valid widget class for the 
exported operation. 

XtCheckSubclass is only executed when the widget has been compiled with the 
compiler symbol DEBUG defined; otherwise, it is defined as the empty string and 
generates no code. 

1.4.7 Superclass Chaining 

While most fields in a widget class structure are self-contained, some fields are linked to 
their corresponding field in their superclass or subclass structures. With a linked field, the 
X Toolkit Intrinsics access it value only after accessing its corresponding superclass value 
(called downward superclass chaining) or before accessing its corresponding superclass 
value (called upward superclass chaining). The self-contained fields in a widget class are: 

• class_name 

• class_initialize 

• widget_size 

• realize 

• visible_interest 

• resize 

• expose 

• accept_focus 

• compress_motion 

• compress_exposure 

• compress_enterleave 

• set values almost 
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• tm_table 

• version 

With downward superclass chaining, the invocation of an operation first accesses the field 
from the Core class structure, then the subclass structure, and so on down the class chain 
to that widget's class structure. These superclass-to-subclass fields are: 

• class_part_initialize 

• get_values_hook 

• initialize 

• initialize_hook 

• set_values 

• set_values_hook 

• resources 

In addition, for subclasses of Constraint, the resources field of the 
ConstraintClassPart structure is chained from the Constraint class down to the 
subclass. 

With upward superclass chaining, the invocation of an operation first accesses the field 
from the widget class structure, then the field from the superclass structure, and so on up 
the class chain to the Core class structure. The subclass-to-superclass fields are: 

• destroy 

• actions 



1.4.8 Class Initialization 

Many class records can be initialized completely at compile time. In some cases, however, 
a class may need to register type converters or perform other sorts of one-time 
initialization. 

Because the C language does not have initialization procedures that are invoked 
automatically when a program starts up, a widget class can declare a class_initialize 
procedure that will be automatically called exactly once by the X Toolkit. A class 
initialization procedure pointer is of type XtProc : 

typedef void (*XtProc ) ( ) ; 
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A widget class indicates that it has no class initialization procedure by specifying NULL in 
the class_initialize field. 

In addition to having class initializations done exactly once, some classes need to perform 
additional initialization for fields in its part of the class record. These are performed not 
just for the particular class but for subclasses as well. This is done in the class's class part 
initialization procedure, which is stored in the class_part_initialize field. The 
class_part_initialize procedure pointer is of type XtWidgetClassProc : 

typedef void (*XtWidgetClassProc ) (WidgetClass ) ; 

During class initialization, the class part initialization procedure for the class and all its 
superclasses are called in superclass-to-subclass order on the class record. These 
procedures have the responsibility of doing any dynamic initializations necessary to their 
class's part of the record. The most common is the resolution of any inherited methods 
defined in the class. For example, if a widget class C has superclasses Core, 
Compos ite, A, and B, the class record for C first is passed to Core's 
class_part_initialize record. This resolves any inherited core methods and compiles the 
textual representations of the resource list and action table that are defined in the class 
record. Next, the Composite's class_part_initialize is called to initialize the composite 
part of C's class record. Finally, the class_part_initialize procedures for A, B, and C (in 
order) are called. For further information, see Section 1.4.9. Classes that do not define 
any new class fields or that need no extra processing for them can specify NULL in the 
class_part_initialize field. 

All widget classes, whether they have a class initialization procedure or not, must start with 
their class_inited field Fa 1 s e . 

The first time a widget of a class is created, XtCreateWidget ensures that the widget 
class and all superclasses are initialized, in superclass to subclass order, by checking each 
class_inited field and if it is False, by calling the class_initialize and the 
class_part_initialize procedures for the class and all its superclasses. The X Toolkit 
Intrinsics then set the class_inited field to True . After the one-time initialization, a class 
structure is constant. 

The following provides the class initialization procedure for Label. 

static void Classlnitialize( ) 
{ 

XtQEleft = XrmStringToQuarkC'left"); 
XtQEcenter = XrmStringToQuark( "center" ) ; 
XtQEright = XrmStringToQuark( "right" ) ; 

XtAddConverter(XtRString, XtRJustify, CvtStringTo Justify , NULL, 0); 

} 
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A class is initialized the first time a widget of that class or any subclass is created. If the 
class initialization procedure registers type converters, these type converters are not 
available until this first widget is created (see Section 9.6). 

1 .4.9 Inheritance of Superclass Operations 

A widget class is free to use any of its superclass's self-contained operations rather than 
implementing its own code. The most frequently inherited operations are: 

• expose 

• realize 

• insert_child 

• delete_child 

• geometry_manager 

• set_values_almost 

To inherit an operation xyz, specify the constant XtlnheritA^yz in your class record. 

Every class that declares a new procedure in its widget class part must provide for 
inheriting the procedure in its class_part_initialize procedure. (The special chained 
operations initialize, set_values, and destroy declared in the Core record do not have 
inherit procedures. Widget classes that do nothing beyond what their superclass does 
specify NULL for chained procedures in their class records.) 

Inheriting works by comparing the value of the field with a known, special value and by 
copying in the superclass's value for that field if a match occurs. This special value is 
usually the X Toolkit Intrinsics internal value _XtInherit cast to the appropriate type. 
(_XtInherit is a procedure that issues an error message if it is actually called.) 

For example, the Composite class's private include file contains these definitions: 

#define XtlnheritGeometryManager ( (XtGeometryHandler ) _XtInherit) 

#define XtlnheritChangeManaged ( (XtWidgetProc ) _XtInherit) 

#define XtlnheritlnsertChild ( (XtArgsProc ) _XtInherit) 

#define XtlnheritDeleteChild ((XtWidgetProc) _XtInherit) 

The Composite's class_part_initialize procedure begins as follows: 

static void CompositeClassPartlnitialize(widgetClass) 
WidgetCiass widgetClass; 

{ 

register CompositeWidgetClass wc = (CompositeWidgetClass ) widgetClass; 
CompositeWidgetClass super = (CompositeWidgetClass) wc->core_class . superclass 
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if (wc->composite_class .geometry_manager == XtlnheritGeometryManager ) { 

wc _ >composite_class . geometry_manager = super->composite_class . geometry_manager ; 

} 

if (wc->composite_class . change_managed == XtlnheritChangeManaged) { 

wc->composite_class . change_managed = super->composite_class . change_managed; 

} 



The inherit constants defined for Core are: 

• XtlnheritRealize 

• XtlnheritResize 

• XtlnheritExpose 

• XtlnheritSetValuesAlmost 

• XtlnheritAcceptFocus 

• XtlnheritDisplayAccelerator 

The inherit constants defined for Composite are: 

• XtlnheritGeometryManager 

• XtlnheritChangeManaged 

• XtlnheritlnsertChild 

• XtlnheritDeleteChild 



1 .4.10 Invocation of Superclass Operations 

A widget class sometimes explicitly needs to call a superclass operation that usually is not 
chained. For example, a widget's expose procedure might call its superclass's expose and 
then perform a little more work of its own. Composite classes with fixed children can 
implement insert_child by first calling their superclass's insert_child procedure and then 
calling XtManageChild to add the child to the managed list. 

Note that a method should call its own superclass method, not the widget's superclass 
method. That is, it should use its own class pointers only, not the widget's class pointers. 
This technique is referred to as enveloping the superclass's operation. 
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Widget Instantiation 



2 



A collection of widget instances constitutes a widget tree. The shell widget returned by 
XtAppCreateShell is the root of the widget tree instance. The widgets with one or 
more children are the intermediate nodes of that tree, and the widgets with no children of 
any kind are the leaves of a widget tree. With the exception of pop-up children (see 
Chapter 5), this widget tree instance defines the associated X Window tree. 

Widgets can be either composite or primitive. Both kinds of widgets can contain children, 
but the X Toolkit Intrinsics provide a set of management mechanisms for constructing and 
interfacing between composite widgets, their children, and other clients. 

Composite widgets, subclasses of Compos ite, are containers for an arbitrary but 
implementation-defined collection of children, which may be instantiated by the composite 
widget itself, by other clients, or by a combination of the two. Composite widgets also 
contain methods for managing the geometry (layout) of any child widget. Under unusual 
circumstances, a composite widget may have zero children, but it usually has at least one. 
By contrast, primitive widgets that contain children typically instantiate specific children of 
known class themselves and do not expect external clients to do so. Primitive widgets also 
do not have general geometry management methods. 

In addition, the X Toolkit Intrinsics recursively perform many operations (for example, 
realization and destruction) on composite widgets and all of their children. Primitive 
widgets that have children must be prepared to perform the recursive operations 
themselves on behalf of their children. 

A widget tree is manipulated by several X Toolkit Intrinsics functions. For example, 
XtRealizeWidget traverses the tree downward and recursively realizes all pop-up 
widgets and children of composite widgets. XtDestroyWidget traverses the tree 
downward and destroys all pop-up widgets and children of composite widgets. The 
functions that fetch and modify resources traverse the tree upward and determine the 
inheritance of resources from a widget's ancestors. XtMakeGeometryRequest 
traverses the tree up one level and calls the geometry manager that is responsible for a 
widget child's geometry. 

To facilitate up-traversal of the widget tree, each widget has a pointer to its parent widget. 
The Shell widget that XtAppCreateShell returns, however, has a parent pointer of 
NULL. 
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To facilitate down-traversal of the widget tree, each composite widget has a pointer to an 
array of children widgets, which includes all normal children created, not just the subset of 
children that are managed by the composite widget's geometry manager. Primitive widgets 
that instantiate children are entirely responsible for all operations that require downward 
traversal below themselves. In addition, every widget has a pointer to an array of pop-up 
children widgets. 



2.1 Initializing the X Toolkit 

Before an application can call any of the X Toolkit Intrinsics functions, it must initialize 
the X Toolkit by using: 

• XtToolkitlnitialize, which initializes the X Toolkit internals 

• XtCreateApplicationContext, which initializes the per application state 

• XtDisplaylnitialize or XtOpenDisplay, which initializes the per display 
state 

• XtAppCreateShell, which creates the initial widget 

Multiple instances of X Toolkit applications may be implemented by a single program in a 
single address space. Each instance needs to be able to read input and dispatch events 
independently of any other instance. Further, an application may need multiple display 
connections or need to have widgets on multiple screens. To accommodate both 
requirements, the X Toolkit Intrinsics define application contexts, each of which provides 
the information needed to distinguish one application instance from another. The major 
component of an application context is a list of X Display pointers for that application. 
The application context type XtAppContext is opaque to clients. 

To initialize the X Toolkit internals, use XtToolkitlnitialize. 

void XtToolkitlnitialize ( ) 

The semantics of calling XtToolkitlnitialize more than once are undefined. 
To create an application context, use XtCreateApplicationContext. 

XtAppContext XtCreateApplicationContext ( ) 

The XtCreateApplicationContext function returns an application context, which 
is an opaque type. Every application must have at least one application context. 
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To destroy an application context and close any displays in it, use 
XtDestroyApplicationContext. 

void XtDestroyApplicationContext (app context) 
XtAppContext app context ; 

app_context Specifies the application context. 

The XtDestroyApplicationContext function destroys the specified application 
context as soon as it is safe to do so. If called from with an event dispatch (for example, a 
callback procedure), XtDestroyApplicationContext does not destroy the 
application context until the dispatch is complete. 

To get the application context for a given widget, use 
XtWidgetToApplicationContext. 

XtAppContext XtWidgetToApplicationContext (w) 
Widget W; 

w Specifies the widget for which you want the application context . 

The XtWidgetToApplicationContext function returns the application context for 
the specified widget. 

To initialize a display and add it to an application context, use 
XtDisp lay Initialize. 

void XtDisplay Initialize (.appcontext , display, application name , application class , 
options, num_options , argc, argy) 
XtAppContext app context ; 
Display *display; 
String application name; 
String application _class ; 
XrmOptionDescRec *options; 
Cardinal num_options ; 
Cardinal *argC; 
String *argv; 

appcontext 
display 

application jiame 
application _class 



Specifies the application context. 

Specifies the display. Note that a display can be in at most one 
application context. 

Specifies the name of the application instance. 

Specifies the class name of this application, which is usually the 
generic name for all instances of this application. 
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options Specifies how to parse the command line for any application- 

specific resources. The options argument is passed as a parameter 
to XrmParse Command. For further information, see 
Programming with Xlib . 

num_options Specifies the number of entries in the options list. 

argc Specifies a pointer to the number of command line parameters. 

argv Specifies the command line parameters. 

The XtDisplaylnitialize function builds the resource database, calls the Xlib 
XrmParseCommand function to parse the command line, and performs other per display 
initialization. After XrmParseCommand has been called, argc and argv contain only 
those parameters that were not in the standard option table or in the table specified by the 
options argument. If the modified argc is not zero, most applications simply print out the 
modified argv along with a message listing the allowable options. The application name is 
usually the final component of argv[0]. If the synchronize resource is True for the 
specified application, XtDisplaylnitialize calls the Xlib XSynchronize 
function to put Xlib into synchronous mode for this display connection. If the 
reverseVideo resource is True , the X Toolkit Intrinsics exchange 
XtDef aultForeground and XtDef aultBackground for widgets created on this 
display. (See Section 9.6.1). 



To open a display, initialize it, and add it to an application context, use 
XtOpenDisplay. 

Display *XtOpenDi splay (app _context , display jtring , application jiame , application class , 
options, num options , argc, argv) 
XtAppContext app _context • 
String display string; 
String application name ; 
String application _class ; 
XrmOpt i onD e s cRe c * options ; 
Cardinal num_options ; 
Cardinal *argc; 
String *a?gv>; 



app_context 
display jtring 

application jiame 
application _class 



Specifies the application context. 

Specifies the display string. Note that a display can be in at most 
one application context. 

Specifies the name of the application instance. 

Specifies the class name of this application, which is usually the 
generic name for all instances of this application. 
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options 



Specifies how to parse the command line for any application- 
specific resources. The options argument is passed as a parameter 
to XrmParseCommand. For further information, see 
Programming with Xlib . 



num_options 



Specifies the number of entries in the options list. 



urge 



Specifies a pointer to the number of command line parameters. 



argv 



Specifies the command line parameters. 



The XtOpenDisplay function calls XOpenDi splay the specified display name. If 
display_string is NULL, XtOpenDisplay uses the current value of the -display option 
specified in argv and if no display is specified in argv, uses the user's default display ( this is 
the value of the DISPLAY environment variable). 

If this succeeds, it then calls XtDisplaylnitialize and pass it the opened display 
and the value of the -name option specified in argv as the application name. If no name 
option is specified, it uses the application name passed to XtOpenDisplay. If the 
application name is NULL, it uses the last component of argv[0]. XtOpenDisplay 
returns the newly opened display or NULL if it failed. 

XtOpenDisplay is provided as a convenience to the application programmer. 

To close a display and remove it from an application context, use XtCloseDisplay. 

void XtCloseDisplay(rfw/j/ay) 
Display ^display; 

display Specifies the display. 

The XtCloseDisplay function closes the specified display as soon as it is safe to do so. 
If called from within an event dispatch (for example, a callback procedure), 
XtCloseDisplay does not close the display until the dispatch is complete. Note that 
applications need only call XtCloseDisplay if they are to continue executing after 
closing the display; otherwise, they should call XtDestroyApplicationContext or 
just exit. 



2.2 Loading the Resource Database 

The XtDisplaylnitialize function loads the application's resource database for this 
display/host/application combination from the following sources (in order): 

• Application-specific class resource file on the client host 
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• Application-specific user resource file on the client host 

• Resource property on the server or user preference resource file on the client host 

• Per-host user environment resource file on the client host 

• Application command line (argv) 

Each resource database is kept on a per-display basis. 

The application-specific class resource file name is constructed from the class name of the 
application. It points to a site-specific resource file that usually is installed by the site 
manager when the application is installed. This file usually is /usr/lib/Xll/app- 
def avilts/ class, where class is the application class name. This file is expected to be 
provided by the developer of the application and may be required for the application to 
function properly. 

The application-specific user resource file name is constructed from the class name of the 
application and points to a user-specific resource file. This file is owned by the application 
and typically stores user customizations. This file name is constructed from the user's 
XAPPLRESDIR variable by appending class to it, where class is the application class 
name. If XAPPLRESDIR is not defined, it defaults to the user's home directory. If the 
resulting resource file exists, it is merged into the resource database. This file may be 
provided with the application or constructed by the user. 

The server resource file is the contents of the X server's RESOURCEMANAGER property 
that was returned by XOpenDi splay. If no such property exists for the display, the 
contents of the resource file in the user's home directory is used instead. The usual name 
for the user preference resource file is . Xde faults . If the resulting resource file exists, 
it is merged into the resource database. The server resource file is constructed entirely by 
the user and contains both display-independent and display-specific user preferences. 

If one exists, a user's environment resource file is then loaded and merged into the 
resource database. This file name is user and host specific. The user's environment 
resource file name is constructed from the value of the user's XENVIRONMENT variable 
for the full path of the file. If this environment variable does not exist, 
XtDisplaylnitialize searches the user's home directory for the . Xdef aults - 
host file, where host is the name of the machine on which the application is running. If the 
resulting resource file exists, it is merged into the resource database. The environment 
resource file is expected to contain process-specific resource specifications that are to 
supplement those user-preference specifications in the server resource file. 

To obtain the resource database for a particular display, use XtDatabase. 

XrmDatabase XtDatabase {display) 
Display ^display; 
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display Specifies the display. 



The XtDatabase function returns the fully merged resource database that was built by 
XtDisplaylnitialize associated with the display that was passed in. If this display 
has not been initialized by XtDisplaylnitialize, the results are not defined. 



2.3 Parsing the Command Line 

The XtOpenDi splay function first parses the command line for the following options: 

-display Specifies the display name for XOpenDisplay, which overrides the 
display name passed to XtDisplaylnitialize. 

-name Sets the resource name prefix, which overrides the application name passed 

to XtDisplaylnitialize. 

XtDisplaylnitialize has a table of standard command line options that are passed 
to XrmParseCommand for adding resources to the resource database, and it takes as a 
parameter additional application-specific resource abbreviations. The format of this table 
is: 



typedef enum { 

XrmoptionNoArg , 
XrmoptionlsArg , 
XrmoptionStickyArg , 
XrmoptionSepArg , 
Xrmopt i onSk i pAr g , 
XrmoptionSkipLine 

} XrmOptionKind; 



/* Value is specified in OptionDescRec .value */ 

/* Value is the option string itself */ 

/* Value is characters immediately following option */ 

/* Value is next argument in argv */ 

/* Ignore this option and the next argument in argv */ 
/* Ignore this option and the rest of argv */ 



typedef struct { 

char *option; 
char *specifier; 
XrmOptionKind argKind; 
caddr t value; 



/* Option name in argv */ 

/* Resource name (without application name) */ 

/* Which style of option it is */ 

/* Value to provide if XrmoptionNoArg */ 



} XrmOptionDescRec , *XrmOptionDescList; 



The standard table contains the following entries: 
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Option String 


Resource Name 


Argument Kind 


Resource Value 


-background 


background 


SepArg 


next argument 


-Du 


borderColor 


SepArg 


next argument 


Vmt 

-og 


background 


SepArg 


next argument 


-borderwidth 


borderWidth 


SepArg 


next argument 


-bordercolor 


borderColor 


SepArg 


next argument 


-bw 


borderWidth 


SepArg 


next argument 


uuspiay 


uispidy 


c\ #-\ A rrr 

ocp^\.rg 


next argument 


-fa 


IU1 Cg,I uuuu 


^ r"\ A f/T 


IlGAl dJgUIIlCIll 


-fn 


fnnf 
lOill 


/l f"\ A »«/T 

ocprvrg 


next argument 


-loni 


frmf 

ioni 


SepArg 


next argument 


-foreground 


foreground 


SepArg 


next argument 


-geometry 


geometry 


SepArg 


next argument 


-iconic 


iconic 


NoArg 


true 


-name 


name 


SepArg 


next argument 


-reverse 


reverseVideo 


NoArg 


on 


-rv 


reverseVideo 


r>o/\rg 


on 


-1- rxr 

T rv 


reverseVideo 


i>o/\rg 


nff 
Oil 


-selectionTimeout 


selectionTimeout 


SepArg 


next argument 


-synchronous 


synchronize 


NoArg 


on 


+ synchronous 


synchronize 


NoArg 


off 


-title 


title 


SepArg 


next argument 


-xrm 


next argument 


ResArg 


next argument 



Note that any unique abbreviation for an option name in the standard table or in the 
application table is accepted. 

If reverseVideo is set, the values of XtDef aultForeground and 

XtDef aultBackground are exchanged. If synchronize is set, the X Toolkit Intrinsics 

put Xlib into synchronous mode for all connections. 

The -xrm option provides a method of setting any resource in an application. The next 
argument should be a quoted string identical in format to a line in the user resources file. 
For example, to give a red background to all command buttons in an application named 
xmh, you can start it up as: 

xmh -xrm ' xmh*Command . background: red' 
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When it parses the command line, XtDisplaylnitialize merges the application 
option table with the standard option table before calling the Xlib XrmParse Command 
function. An entry in the application table with the same name as an entry in the standard 
table overrides the standard table entry. If an option name is a prefix of another option 
name, both names are kept in the merged table. 



2.4 Creating Widgets 

The creation of widget instances is a three-phase process: 

1. The widgets are allocated and initialized with resources and are optionally added to 
the managed subset of their parent. 

2. All composite widgets are notified of their managed children in a bottom-up 
traversal of the widget tree. 

3. The widgets create X windows that then get mapped. 

To start the first phase, the application calls XtCreateWidget for all its widgets and 
adds some (usually, most or all) of its widgets to their respective parent's managed set by 
calling XtManageChild. To avoid an O (n 2 ) creation process where each composite 
widget lays itself out each time a widget is created and managed, parent widgets are not 
notified of changes in their managed set during this phase. 

After all widgets have been created, the application calls XtRealizeWidget on the 
top-level widget to start the second and third phases. XtRealizeWidget first 
recursively traverses the widget tree in a post-order (bottom-up) traversal and then notifies 
each composite widget with one or more managed children by means of its 
change_managed procedure. 

Notifying a parent about its managed set involves geometry layout and possibly geometry 
negotiation. A parent deals with constraints on its size imposed from above (for example, 
when a user specifies the application window size) and suggestions made from below (for 
example, when a primitive child computes its preferred size). One difference between the 
two can cause geometry changes to ripple in both directions through the widget tree. The 
parent may force some of its children to change size and position and may issue geometry 
requests to its own parent in order to better accommodate all its children. You cannot 
predict where anything will go on the screen until this process finishes. 

Consequently, in the first and second phases, no X windows are actually created because it 
is likely that they will get moved around after creation. This avoids unnecessary requests 
to the X server. 
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Finally, XtRealizeWidget starts the third phase by making a pre-order (top-down) 
traversal of the widget tree, allocates an X window to each widget by means of its realize 
procedure, and finally maps the widgets that are managed. 

2.4.1 Creating and Merging Argument Lists 

Many X Toolkit Intrinsics functions need to be passed pairs of resource names and values. 
These are passed as an ArgList, which contains: 

typedef something XtArgVal; 

typedef struct { 

String name; 

XtArgVal value; 
} Arg, *ArgList; 

Where something is a type large enough to contain caddr_t, char *, long, int *, or a pointer 
to a function. 

If the size of the resource is less than or equal to the size of an XtArgVal, the resource 
value is stored directly in value; otherwise, a pointer to it is stored into value. 

To set values in an ArgList, use XtSetArg. 

XtSetArg (a/g, name, value) 
Arg arg; 
String name; 
XtArgVal value; 

arg Specifies the name-value pair to set. 
name Specifies the name of the resource. 

value Specifies the value of the resource if it will fit in an XtArgVal or the address. 

The XtSetArg function is usually used in a highly stylized manner to minimize the 
probability of making a mistake; for example: 

Arg args [20] ; 
int n; 

n = 0; 

XtSetArg (args [n] , XtNheight, 100); n++; 
XtSetArg (args [n] , XtNwidth, 200); n++; 
XtSetValues (widget, args, n); 

Alternatively, an application can statically declare the argument list and use XtNumber : 
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static Args ar(;s[] = { 

{XtNheight, (XtArgVal) 100}, 
{XtNwidth, (XtArgVal) 200}, 

}; 

XtSetValues (Widget, args, XtNumber(args) ) ; 



Note that you should not use auto-increment or auto-decrement within the first argument 
to XtSetArg. XtSetArg can be implemented as a macro that dereferences the first 
argument twice. 



To merge two ArgList structures, use XtMergeArgLists. 

ArgList XtMergeArgLists {argsl , num argsl , args2 , num_args2) 
ArgList argsl; 
Cardinal num argsl ; 
ArgList args2; 
Cardinal num. _args2 ; 

argsl Specifies the first ArgList. 

num_argsl Specifies the number of arguments in the first argument list. 

argsl Specifies the second ArgList. 

num_args2 Specifies the number of arguments in the second argument list. 

The XtMergeArgLists function allocates enough storage to hold the combined 
ArgList structures and copies them into it. Note that it does not check for duplicate 
entries. When it is no longer needed, free the returned storage by using XtFree. 



2.4.2 Creating a Widget Instance 

To create an instance of a widget, use XtCreateWidget. 

Widget XtCreateWidget {name, widget class , parent, args, numargs) 
String name; 
WidgetClass widget _class ; 
Widget parent; 
ArgList orgs; 
Cardinal numjvrgs; 



name Specifies the resource name for the created widget, which is used for 

retrieving resources and, for that reason, should not be the same as any 
other widget that is a child of same parent. 

widget _class Specifies the widget class pointer for the created widget. 

parent Specifies the parent widget. 
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args Specifics the argument list to override the resource defaults. 

num args Specifics the number of arguments in the argument list. 

The XtCreateWidget function performs much of the boilerplate operations of widget 
creation: 

• Checks to sec if the classinitialize procedure has been called for this class and for 
all superclasses and, if not, calls those necessary in a superclass-to-subclass order. 

• Allocates memory for the widget instance. 

• If the parent is a subclass of constraintWidgetClass, it allocates memory for 
the parent's constraints and stores the address of this memory into the constraints 
field. 

• Initializes the core nonresourcc data fields (for example, parent and visible). 

• Initializes the resource fields (for example, background pixel) by using the resource 
lists specified for this class and all superclasses. 

• If the parent is a subclass of constraintWidgetClass, it initializes the 
resource fields of the constraints record by using the constraint resource list 
specified for the parent's class and all superclasses up to 
constraintWidgetClass . 

• Calls the initialize procedures for the widget by starting at the Core initialize 
procedure on down to the widget's initialize procedure. 

• If the parent is a subclass of compositeWidgetClass, it puts the widget into its 
parent's children list by calling its parent's insertchild procedure. For further 
information, see Section 3.5. 

• If the parent is a subclass of constraintWidgetClass, it calls the constraint 
initialize procedures, starting at constraintWidgetClass on down to the 
parent's constraint initialize procedure. 

Note that you can determine the number of arguments in an argument list by using the 
XtNumber macro. For further information, see Section 11.1. (See also 
XtCr ea teManagedWidge t .) 
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2.4.3 Creating an Application Shell Instance 



An application can have multiple top-level widgets, which can potentially be on many 
different screens. An application uses XtAppCreateShell if it needs to have several 
independent windows. The XtAppCreateShell function creates a top-level widget 
that is the root of a widget tree. 



Widget XtAppCreateShell (application jiame , application class , widget class , display, 
orgs, numargs) 
String application name ; 
String application _class ; 
WidgetClass widget class ; 
Display *display; 
ArgList orgs; 
Cardinal num_args ; 



application jiame Specifies the name of the application instance. If 

application_name is NULL, the application name passed to 
XtDisplaylnitialize is used. 

application _class Specifies the class name of this application. 

widget _class Specifies the widget class that the application top-level widget 

should be (normally, applicationShellWidgetClass) . 

display Specifies the display from which to get the resources. 

args Specifies the argument list in which to set in the WMCOMMAND 

property. 

num_args Specifies the number of arguments in the argument list. 

The XtAppCreateShell function saves the specified application name and application 
class for qualifying all widget resource specifiers. The application name and application 
class are used as the left-most components in all widget resource names for this 
application. XtAppCreateShell should be used to create a new logical application 
within a program or to create a shell on another display. In the first case, it allows the 
specification of a new root in the resource hierarchy. In the second case, it uses the 
resource database associated with the other display. 

Note that the widget returned by XtAppCreateShell has the WM COMMAND 
property set for session managers (see Chapter 4). 

To create multiple top-level shells within a single (logical) application, you can use one of 
two methods: 

• Designate one shell as the real top-level shell and create the others as pop-up 
children of it by using XtCreatePopupShell. 
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• Have all shells as pop-up children of an unrealized top-level shell. 

The first method, which is best used when there is a clear choice for what is the main 
window, leads to resource specifications like the following: 

xmail . geometry :.. . (the main window) 

xmail. read. geometry: . . . (the read window) 
xmail. compose. geometry: . . . (the compose window) 

The second method, which is best if there is no main window, leads to resource 
specifications like the following: 

xmail. headers . geometry :... (the headers window) 
xmail . read . geometry :.. . (the read window) 
xmail . compose . geometry : . . . (the compose window) 

2.4.4 Widget Instance Initialization 

The initialize procedure pointer in a widget class is of type XtlnitProc : 

typedef void (*XtInitProc ) (Widget , Widget); 
Widget request; 
Widget new; 

request Specifies the widget with resource values as requested by the argument list, the 
resource database, and the widget defaults. 

new Specifies a widget with the new values, both resource and nonresource, that 

are actually allowed. 

An initialization procedure performs the following: 

• Allocates space for and copies any resources that are referenced by address. For 
example, if a widget has a field that is a String it cannot depend on the characters 
at that address remaining constant but must dynamically allocate space for the string 
and copy it to the new space. (Note that you should not allocate space for or copy 
callback lists.) 

• Computes values for unspecified resource fields. For example, if width and height 
are zero, the widget should compute an appropriate width and height based on other 
resources. This is the only time that a widget should ever directly assign its own 
width and height. 

• Computes values for uninitialized nonresource fields that are derived from resource 
fields. For example, graphics contexts (GCs) that the widget uses are derived from 
resources like background, foreground, and font. 
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An initialization procedure also can check certain fields for internal consistency. For 
example, it makes no sense to specify a color map for a depth that does not support that 
color map. 

Initialization procedures are called in superclass-to-subclass order. Most of the 
initialization code for a specific widget class deals with fields defined in that class and not 
with fields defined in its superclasses. 

If a subclass does not need an initialization procedure because it does not need to perform 
any of the above operations, it can specify NULL for the initialize field in the class record. 

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, 
size calculations of a superclass are often incorrect for a subclass and in this case, the 
subclass must modify or recalculate fields declared and computed by its superclass. 

As an example, a subclass can visually surround its superclass display. In this case, the 
width and height calculated by the superclass initialize procedure are too small and need to 
be incremented by the size of the surround. The subclass needs to know if its superclass's 
size was calculated by the superclass or was specified explicitly. All widgets must place 
themselves into whatever size is explicitly given, but they should compute a reasonable size 
if no size is requested. 

The request and new arguments provide the necessary information for how a subclass 
knows the difference between a specified size and a size computed by a superclass. The 
request widget is the widget as originally requested. The new widget starts with the values 
in the request, but it has been updated by all superclass initialization procedures called so 
far. A subclass initialize procedure can compare these two to resolve any potential 
conflicts. 

In the above example, the subclass with the visual surround can see if the width and height 
in the request widget are zero. If so, it adds its surround size to the width and height fields 
in the new widget. If not, it must make do with the size originally specified. 

The new widget will become the actual widget instance record. Therefore, the 
initialization procedure should do all its work on the new widget (the request widget 
should never be modified), and if it needs to call any routines that operate on a widget, it 
should specify new as the widget instance. 

2.4.5 Constraint Widget Instance Initialization 

The constraint_initialize procedure pointer is of type XtlnitProc. The values passed 
to the parent constraint initialization procedure are the same as those passed to the child's 
class widget initialization procedure. 
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The constraint initialization procedure should compute any constraint fields derived from 
constraint resources. It can make further changes to the widget to make the widget 
conform to the specified constraints, for example, changing the widget's size or position. 

If a constraint class does not need a constraint initialization procedure, it can specify 
NULL for the initialize field of the Cons trail :( lassPart in the class record. 

2.4.6 Nonwidget Data Initialization 

The initialize hook procedure pointer is of type XtArgsProc: 

typedef void (*XtArgsProc ) (Widget , ArgList, Cardinal *); 
Widget W; 
ArgList orgs; 
Cardinal *num_args ; 

w Specifics the widget. 

args Specifics the argument list to override the resource defaults. 

num args Specifies the number of arguments in the argument list. 

If this procedure is not NULL, it is called immediately after the corresponding initialize 
procedure or in its place if the initialize procedure is NULL. 

The initialize hook procedure allows a widget instance to initialize nonwidget data using 
information from the specified argument list. For example, the Text widget has subparts 
that are not widgets, yet these subparts have resources that can be specified by means of 
the resource file or an argument list. Sec also Section 9.4. 



2.5 Realizing Widgets 

To realize a widget instance, use XtRealizeWidget. 

void XtRealizeWidgetCw) 
Widget W; 

w Specifics the widget. 

If the widget is already realized, XtRealizeWidget simply returns. Otherwise, it 
performs the following: 

• Binds all action names in the widget's translation table to procedures (see Section 
10.1.2). 
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• Makes a post-order traversal of the widget tree rooted at the specified widget and 
calls the change_managed procedure of each composite widget that has one or more 
managed children. 

• Constructs an XSetWindowAttributes structure filled in with information 
derived from the Core widget fields and calls the realize procedure for the widget, 
which adds any widget-specific attributes and creates the X window. 

• If the widget is not a subclass of compos iteWidgetClass, 
XtRealizeWidget returns; otherwise, it continues and performs the following: 

• Descends recursively to each of the widget's managed children and calls the 
realize procedures. Primitive widgets that instantiate children are responsible 
for realizing those children themselves. 

• Maps all of the managed children windows that have mapped_when_managed 
True. (If a widget is managed but mapped_when_managed is False, the 
widget is allocated visual space but is not displayed. Some people seem to like 
this to indicate certain states.) 

If the widget is a top-level shell widget (that is, it has no parent), and 
mapped_when_managed is True, XtRealizeWidget maps the widget window. 

XtCreateWidget, XtRealizeWidget, XtManage Children, 
XtUnmanageChildren, and XtDes troyWidget maintain the following invariants: 

• If a widget is realized, then all its managed children are realized. 

• If a widget is realized, then all its managed children that are also 
mapped_when_managed are mapped. 

All X Toolkit Intrinsics functions and all widget routines should work with either realized 
or unrealized widgets. 

To check whether or not a widget has been realized, use XtlsRealized. 

Boolean XtlsRealized(H') 
Widget w; 

w Specifies the widget. 

The XtlsRealized function returns True if the widget has been realized, that is, if 
the widget has a nonzero X window ID. 

Some widget procedures (for example, set_values) might wish to operate differently after 
the widget has been realized. 
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2.5.1 Widget Instance Window Creation 

The realize procedure pointer in a widget class is of type XtRealizeProc : 

typedef void (*XtRealizeProc) (Widget, XtValueMask *, XSetWindowAttributes *); 
Widget w; 

XtValueMask *value_mask; 
XSetWindowAttributes ^attributes ; 

w Specifies the widget. 

value mask Specifies which fields in the attributes structure to use. 

attributes Specifies the window attributes to use in the XCreateWindow call. 

The realize procedure must create the widget's window. 

The generic XtRealizeWidget function fills in a mask and a corresponding 
XSetWindowAttributes structure. It sets the following fields based on information in 
the widget Core structure: 

• The background_pixmap (or backgroundpixel if backgroundpixmap is NULL) is 
filled in from the corresponding field. 

• The borderpixmap (or border_pixel if border_pixmap is NULL) is filled in from the 
corresponding field. 

• The event_mask is filled in based on the event handlers registered, the event 
translations specified, whether expose is non-NULL, and whether visible_interest is 
True. 

• The bit gravity is set to NorthWestGravity if the expose field is NULL. 

• The do not propagate mask is set to propagate all pointer and keyboard events up 
the window tree. A composite widget can implement functionality caused by an 
event anywhere inside it (including on top of children widgets) as long as children do 
not specify a translation for the event. 

All other fields in attributes (and the corresponding bits in valuemask) can be set by the 
realize procedure. 

Note that because realize is not a chained operation, the widget class realize procedure 
must update the XSetWindowAttributes structure with all the appropriate fields 
from non-Core superclasses. 

A widget class can inherit its realize procedure from its superclass during class 
initialization. The realize procedure defined for Core calls XtCreateWindow with 
the passed value mask and attributes and with windowClass and visual set to 
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CopyFromParent. Both CompositeWidgetClass and 
ConstraintWidgetClass inherit this realize procedure, and most new widget 
subclasses can do the same (see Section 1.4.9). 

The most common noninherited realize procedures set bit_gravity in the mask and 
attributes to the appropriate value and then create the window. For example, depending 
on its justification, Label sets bit_gravity to Wes tGravity, CenterGravi ty , or 
EastGravity. Consequently, shrinking it just moves the bits appropriately, and no 
Expose event is needed for repainting. 

If a composite widget's children should be realized in a particular order (typically to 
control the stacking order), it should call XtRealizeWidget on its children itself in the 
appropriate order from within its own realize procedure. 

Widgets that have children and that are not a subclass of CompositeWidgetClass are 
responsible for calling XtRealizeWidget on their children, usually from within the 
realize procedure. 



2.5.2 Window Creation Convenience Routine 

Rather than call the Xlib XCreateWindow function explicitly, a realize procedure 
should call the X Toolkit Intrinsics analog XtCreateWindow, which simplifies the 
creation of windows for widgets. 

void XtCreateWindow(H', window _class , visual, valuejnask, attributes) 
Widget W; 

unsigned int window class ; 
Visual *visual; 
XtValueMask valuejnask; 
XSetWindowAttributes * attributes ; 



w Specifies the widget that is used to set the x,y coordinates and so on. 

window _class Specifies the Xlib window class (for example, InputOutput, 
InputOnly, or CopyFromParent). 

visual Specifies the visual type (usually CopyFromParent). 

valuejnask Specifies which attribute fields to use. 

attributes Specifies the window attributes to use in the XCreateWindow call. 

The XtCreateWindow function calls the Xlib XCreateWindow function with values 
from the widget structure and the passed parameters. Then, it assigns the created window 
to the widget's window field. 

XtCreateWindow evaluates the following fields of the Core widget structure: 
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• depth 

• screen 

• parent - > core.window 

• x 

• y 

• width 

• height 

• border width 



2.6 Obtaining Window Information from a Widget 

The Core widget definition contains the screen and window IDs. The window field may 
be NULL for a while (see Sections 2.4 and 2.5). 

The display pointer, the parent widget, screen pointer, and window of a widget are 
available to the widget writer by means of macros and to the application writer by means 
of functions. 

Display *XtDisplay(»v) 
Widget w; 

w Specifies the widget. 

XtDi splay returns the display pointer for the specified widget. 

Widget XtParent(H') 
Widget W; 

w Specifies the widget. 

XtParent returns the parent widget for the specified widget. 

Screen *XtScreen(M>) 
Widget W; 
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iv Specifies the widget. 

XtScreen returns the screen pointer for the specified widget. 



Window XtWindow(H>) 
Widget w; 

w Specifies the widget. 

XtWindow returns the window of the specified widget. 

Several window attributes are locally cached in the widget. Thus, they can be set by the 
resource manager and XtSetValues as well as used by routines that derive structures 
from these values (for example, depth for deriving pixmaps, background_pixel for deriving 
GCs, and so on) or in the XtCreateWindow call. 

The x, y, width, height, and border_width window attributes are available to geometry 
managers. These fields are maintained synchronously inside the X Toolkit. When an 
XConf igureWindow is issued on the widget's window (on request of its parent), these 
values are updated immediately rather than sometime later when the server generates a 
Conf igureNotify event. (In fact, most widgets do not have 
Subs true tureNot if y turned on.) This ensures that all geometry calculations are 
based on the internally consistent toolkit world, rather than on either an inconsistent world 
updated by asynchronous Conf igureNotify events or a consistent but slow world in 
which geometry managers ask the server for window sizes whenever they need to lay out 
their managed children (see Chapter 6). 

2.6.1 Unrealizing Widgets 

To destroy the windows associated with a widget and its descendants, use 
XtUnrealizeWidget. 

void XtUnrealizeWidgetCw) 
Widget W; 

w Specifies the widget. 

The XtUnrealizeWidget function destroys the windows of an existing widget and all 
of its children (recursively down the widget tree). To recreate the windows at a later time, 
call XtRealizeWidget again. If the widget was managed, it will be unmanaged 
automatically before its window is freed. 
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2.7 Destroying Widgets 

The X Toolkit Intrinsics provide support to: 

• Destroy all the pop-up children of the widget being destroyed and destroy all 
children of composite widgets 

• Remove (and unmap) the widget from its parent 

• Call the callback procedures that have been registered to trigger when the widget is 
destroyed 

• Minimize the number of things a widget has to deallocate when destroyed 

• Minimize the number of XDestroyWindow calls 

To destroy a widget instance, use XtDestroyWidget. 

void XtDestroyWidget (h>) 
Widget w; 

w Specifies the widget. 

The XtDestroyWidget function provides the only method of destroying a widget, 
including widgets that need to destroy themselves. It can be called at any time, including 
from an application callback routine of the widget being destroyed. This requires a two- 
phase destroy process in order to avoid dangling references to destroyed widgets. 

In phase one, XtDestroyWidget performs the following: 

• If the being_destroyed field of the widget is True , it returns immediately. 

• Recursively descends the widget tree and sets the being_destroyed field to True for 
the widget and all children. 

• Adds the widget to a list of widgets (the destroy list) that should be destroyed when 
it is safe to do so. 

Entries on the destroy list satisfy the invariant that if w2 occurs after wl on the destroy list 
then w2 is not a descendent of wl. (A descendant refers to both normal and pop-up 
children.) 

Phase two occurs when all procedures that should execute as a result of the current event 
have been called (including all procedures registered with the event and translation 
managers), that is, when the current invocation of XtDispatchEvent is about to return 
or immediately if not in XtDispatchEvent. 
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In phase two, XtDestroyWidget performs the following on each entry in the destroy 
list: 

• Calls the destroy callback procedures registered on the widget (and all descendants) 
in post-order (it calls children callbacks before parent callbacks). 

• If the widget's parent is a subclass of compos iteWidgetClass and if the parent 
is not being destroyed, it calls XtUnmanageChild on the widget and then calls 
the widget's parent's delete_child procedure (see Section 3.4). 

• If the widget's parent is a subclass of constraintWidgetClass, it calls the 
constraint destroy procedure for the parent, then the parent's superclass, until finally 
it calls the constraint destroy procedure for constraintWidgetClass. 

• Calls the destroy methods for the widget (and all descendants) in post-order. For 
each such widget, it calls the destroy procedure declared in the widget class, then the 
destroy procedure declared in its superclass, until finally it calls the destroy 
procedure declared in the Core class record. 

• Calls XDes troyWindow if the widget is realized (that is, has an X window). The 
server recursively destroys all descendant windows. 

• Recursively descends the tree and deallocates all pop-up widgets, constraint records, 
callback lists and, if the widget is a subclass of compos iteWidgetClass, 
children. 



2.7.1 Adding and Removing Destroy Callbacks 

When a application needs to perform additional processing during the destruction of a 
widget, it should register a destroy callback procedure for the widget. The destroy callback 
procedures use the mechanism described in Chapter 8. The destroy callback list is 
identified by the resource name XtNdestroyCallback. 

For example, the following adds an application-supplied destroy callback procedure 
ClientDestroy with client data to a widget by calling XtAddCallback. 

XtAddCallback(M>, XtNdestroyCallback, ClientDestroy, client JLata) 

Similarly, the following removes the application-supplied destroy callback procedure 
ClientDestroy by calling XtRemoveCallback. 

XtRemoveCallback(M>, XtNdestroyCallback, ClientDestroy, client_data) 
The ClientDestroy argument is of type XtCallbackProc: 



Widget Instantiation 2 - 23 



typedef void (*XtCallbackProc ) (Widget, caddr_t, caddr_t); 

For further information, see Section 8.1. 

2.7.2 Dynamic Data Deallocation 

The destroy procedure pointer in the CoreClassPart structure is of type 
XtWidgetProc: 

typedef void (*XtWidgetProc) (Widget) ; 

The destroy procedures are called in subclass-to-superclass order. Therefore, a widget's 
destroy procedure only should deallocate storage that is specific to the subclass and should 
not bother with the storage allocated by any of its superclasses. The destroy procedure 
should only deallocate resources that have been explicitly created by the subclass. Any 
resource that was obtained from the resource database or was passed in in an argument 
list was not created by the widget and, therefore, should not be destroyed by it. If a widget 
does not need to deallocate any storage, the destroy procedure entry in its widget class 
record can be NULL. 

Deallocating storage includes but is not limited to: 

• Calling XtFree on dynamic storage allocated with XtMalloc, XtCalloc, and 
so on 

• Calling XFreePixmap on pixmaps created with direct X calls 

• Calling XtDestroyGC on GCs allocated with XtGetGC 

• Calling XFreeGC on GCs allocated with direct X calls 

• Calling XtRemoveEventHandler on event handlers added with 
XtAddEventHandler 

• Calling XtRemoveTimeOut on timers created with XtAppAddTimeOut 

• Calling XtDestroyWidget for each child if the widget has children and is not a 
subclass of compositeWidgetClass 



2 - 24 Widget Instantiation 



2.7.3 Dynamic Constraint Data Deallocation 



The constraint destroy procedure identified in the Cons traintClass Part structure is 
called for a widget whose parent is a subclass of cons traintWidgetClass . This 
constraint destroy procedure pointer is of type XtWidgetProc. The constraint destroy 
procedures are called in subclass-to-superclass order, starting at the widget's parent and 
ending at cons traintWidge tClass . Therefore, a parent's constraint destroy 
procedure only should deallocate storage that is specific to the constraint subclass and not 
the storage allocated by any of its superclasses. 

If a parent does not need to deallocate any constraint storage, the constraint destroy 
procedure entry in its class record can be NULL. 



2.8 Exiting from an Application 

All X Toolkit applications should terminate by calling 

XtDestroyApplicationContext and then exiting using the standard method for 
their operating system (typically, by calling exit ). The quickest way to make the 
windows disappear while exiting is to call XtUnmapWidget on each top-level shell 
widget. The X Toolkit has no resources beyond those in the program image, and the X 
server will free its resources when its connection to the application is broken. 



Widget Instantiation 2 - 25 



Composite Widgets and Their Children 



3 



Composite widgets (widgets that are a subclass of compos iteWidgetClass) can have 
an arbitrary number of children. Consequently, they are responsible for much more than 
primitive widgets. Their responsibilities (either implemented directly by the widget class 
or indirectly by X Toolkit Intrinsics functions) include: 

• Overall management of children from creation to destruction 

• Destruction of descendants when the composite widget is destroyed 

• Physical arrangement (geometry management) of a displayable subset of children 
(that is, the managed children) 

• Mapping and unmapping of a subset of the managed children 

Overall management is handled by the generic procedures XtCreateWidget and 
XtDestroyWidget. XtCreateWidget adds children to their parent by calling the 
parent's insert_child procedure. XtDestroyWidget removes children from their 
parent by calling the parent's delete_child procedure and ensures that all children of a 
destroyed composite widget also get destroyed. 

Only a subset of the total number of children is actually managed by the geometry 
manager and, hence, possibly visible. For example, a multibuffer composite editor widget 
might allocate one child widget for each file buffer, but it only might display a small 
number of the existing buffers. Windows that are in this displayable subset are called 
managed windows and enter into geometry manager calculations. The other children are 
called unmanaged windows and, by definition, are not mapped. 

Children are added to and removed from the managed set by using XtManageChild, 
XtManageChildren, XtUnmanageChild, and XtUnmanageChildren, which 
notify the parent to recalculate the physical layout of its children by calling the parent's 
change_managed procedure. The XtCreateManagedWidget convenience function 
calls XtCreateWidget and XtManageChild on the result. 

Most managed children are mapped, but some widgets can be in a state where they take up 
physical space but do not show anything. Managed widgets are not mapped automatically 
if their map_when_managed field is False. The default is True and is changed by 
using XtSetMappedWhenManaged. 



Composite Widgets and Their Children 3-1 



Each composite widget class has a geometry manager, which is responsible for figuring out 
where the managed children should appear within the composite widget's window. 
Geometry management techniques fall into four classes: 



• Fixed boxes 

Fixed boxes have a fixed number of children that are created by the parent. All of 
these children are managed, and none ever make geometry manager requests. 

• Homogeneous boxes 

Homogeneous boxes treat all children equally and apply the same geometry 
constraints to each child. Many clients insert and delete widgets freely. 

• Heterogeneous boxes 

Heterogeneous boxes have a specific location where each child is placed. This 
location usually is not specified in pixels, because the window may be resized, but is 
expressed rather in terms of the relationship between a child and the parent or 
between the child and other specific children. Heterogeneous boxes are usually 
subclasses of Constraint. 

• Shell boxes 

Shell boxes have only one child, which is exactly the size of the shell. The geometry 
manager must communicate with the window manager if it exists, and the box must 
also accept Conf igureNotify events when the window size is changed by the 
window manager. 



3.1 Verifying the Class of a Composite Widget 

To test if a given widget is a subclass of Composite, use XtlsComposite. 

Boolean XtlsComposite (*v) 
Widget W; 

w Specifies the widget. 

The XtlsComposite function is a convenience function that is equivalent to 
XtlsSubclass with compos iteWidgetClass specified. 
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3.2 Addition of Children to a Composite Widget 

To add a child to the parent's list of children, the XtCreateWidget function calls the 
parent's class routine insert_child. The insert_child procedure pointer in a composite 
widget is of type XtWidgetProc: 

typedef void (*XtWidgetProc) (Widget) ; 

Most composite widgets inherit their superclass's operation. Composite's insert_child 
routine calls the insert_position procedure and inserts the child at the specified position. 

Some composite widgets define their own insert_child routine so that they can order then- 
children in some convenient way, create companion controller widgets for a new widget, or 
limit the number or type of their children widgets. 

If there is not enough room to insert a new child in the children array (that is, 
num_children = num_slots), the insert_child procedure must first reallocate the array and 
update num_slots. The insert_child procedure then places the child wherever it wants and 
increments the num children field. 



3.3 Insertion Order of Children 

Instances of composite widgets need to specify about the order in which their children are 
kept. For example, an application may want a set of command buttons in some logical 
order grouped by function, and it may want buttons that represent file names to be kept in 
alphabetical order. 

The insert_position procedure pointer in a composite widget instance is of type 
XtOrderProc: 

typedef Cardinal (*XtOrderProc) (Widget) ; 
Widget W; 

w Specifies the widget. 

Composite widgets that allow clients to order their children (usually homogeneous boxes) 
can call their widget instance's insert_position procedure from the class's insert_child 
procedure to determine where a new child should go in its children array. Thus, a client of 
a composite class can apply different sorting criteria to widget instances of the class, 
passing in a different insert_position procedure when it creates each composite widget 
instance. 
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The return value of the insert_position procedure indicates how many children should go 
before the widget. Returning zero indicates that the widget should go before all other 
children, and returning num_children indicates that it should go after all other children. 
The default insert_position function returns num_children and can be overridden by a 
specific composite widget's resource list or by the argument list provided when the 
composite widget is created. 



3.4 Deletion of Children 

To remove the child from the parent's children array, the XtDestroyWidget function 
eventually causes a call to the composite parent's class delete_child procedure. The 
delete_child procedure pointer is of type XtWidgetProc: 

typedef void (*XtWidgetProc) (Widget) ; 

Most widgets inherit the delete_child procedure from their superclass. Composite widgets 
that create companion widgets define their own delete_child procedure to remove these 
companion widgets. 



3.5 Adding and Removing Children from the Managed Set 

The X Toolkit Intrinsics provide a set of generic routines to permit the addition of widgets 
to or the removal of widgets from a composite widget's managed set. These generic 
routines eventually call the widget's change_managed procedure. The changejmanaged 
procedure pointer is of type XtWidgetProc. 

3.5.1 Managing Children 

To add a list of widgets to the geometry-managed (and, hence, displayable) subset of its 
composite parent widget, the application must first create the widgets 
(XtCreateWidget) and then call XtManageChildren. 

typedef Widget *WidgetList; 

void XtManageChildren(c/i/Wren, num_children) 
WidgetList children; 
Cardinal num_children; 

children Specifies a list of child widgets. 

num_children Specifies the number of children. 

The XtManageChildren function performs the following: 
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• Issues an error if the children do not all have the same parent or if the parent is not 
a subclass of compos iteWidgetClass. 

• Returns immediately if the common parent is being destroyed; otherwise, for each 
unique child on the list, XtManage Children ignores the child if it already is 
managed or is being destroyed and marks it if not. 

• If the parent is realized and after all children have been marked, it makes some of 
the newly managed children viewable: 

• Calls the change_managed routine of the widgets' parent. 

• Calls XtRealizeWidget on each previously unmanaged child that is 
unrealized. 

• Maps each previously unmanaged child that has map_when_managed True . 

Managing children is independent of the ordering of children and independent of creating 
and deleting children. The layout routine of the parent should consider children whose 
managed field is True and should ignore all other children. Note that some composite 
widgets, especially fixed boxes, call XtManageChild from their insert_child procedure. 

If the parent widget is realized, its change_managed procedure is called to notify it that its 
set of managed children has changed. The parent can reposition and resize any of its 
children. It moves each child as needed by calling XtMoveWidget, which first updates 
the x and y fields and then calls XMoveWindow if the widget is realized. 

If the composite widget wishes to change the size or border width of any of its children, it 
calls XtResizeWidget, which first updates the Core fields and then calls the Xlib 
XConf igureWindow function if the widget is realized. 

To add a single child to a parent widget's list of managed children, first create the child 
widget (XtCreateWidget) and then use XtManageChild. 

void XtManageChild(cMd) 
Widget child; 

child Specifies the child. 

The XtManageChild function constructs a WidgetList of length one and calls 
XtManageChildren. 

To create and manage a child widget in a single procedure, use 
XtCreateManagedWidget. 
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Widget XtCreateManagedWidget (/u#ne, widget _class , parent, orgs, numjtrgs) 
String name; 
WidgetClass widget _class; 
Widget parent; 
ArgList orgs; 
Cardinal numjtrgs; 

name Specifies the text name for the created widget. 

widget jzlass Specifies the widget class pointer for the created widget. 



The XtCreateManagedWidget function is a convenience routine that calls 
XtCreateWidget and XtManageChild. 

3.5.2 Unmanaging Children 

To remove a list of children from a parent widget's managed list, use 
XtUnmanage Chi 1 dr en . 

void XtUnmanageChildren(c/»7<fre/i, num_children) 
WidgetList children; 
Cardinal numjchildren ; 

children Specifies a list of child widgets. 

num_children Specifies the number of children. 

The XtUnmanageChildren function performs the following: 

• Issues an error if the children do not all have the same parent or if the parent is not 
a subclass of compositeWidgetClass. 

• Returns immediately if the common parent is being destroyed; otherwise, for each 
unique child on the list, XtUnmanageChildren performs the following: 

• Ignores the child if it already is unmanaged or is being destroyed and marks it if 
not. 

• If the child is realized, it makes it nonvisible by unmapping it. 

• Calls the change_managed routine of the widgets' parent after all children have been 
marked if the parent is realized. 



parent 



num _args 



args 



Specifies the 
Specifies the 
Specifies the 



parent widget. 

argument list to override the resource defaults, 
number of arguments in the argument list. 
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XtUnmanage Children does not destroy the children widgets. Removing widgets from 
a parent's managed set is often a temporary banishment, and, some time later, you may 
manage the children again. To destroy widgets entirely, see Section 2.7. 

To remove a single child from its parent's managed set, use XtUnmanageChild. 

void XtUnmanageChildCcMd 1 ) 
Widget child; 

child Specifies the child. 

The XtUnmanageChild function constructs a widget list of length one and calls 
XtUnmanage Children. 

These generic functions are low-level routines that are used by generic composite widget 
building routines. In addition, composite widgets can provide widget-specific, high-level 
convenience procedures to let applications create and manage children more easily. 

3.5.3 Determining if a Widget Is Managed 

To determine the managed state of a given child widget, use XtlsManaged. 

Boolean XtIsManaged(M>) 
Widget w; 

w Specifies the widget. 

The XtlsManaged macro (for widget programmers) or function (for application 
programmers) returns True if the specified child widget is managed or False if it is 
not. 



3.6 Controlling When Widgets Get Mapped 

A widget is normally mapped if it is managed. However, this behavior can be overridden 
by setting the XtNmappedWhenManaged resource for the widget when it is created or by 
setting the map_when_managed field to Fal s e . 

To change the value of a given widget's map_when_managed field, use 
XtSetMappedWhenManaged. 

void XtSetMappedWhenManaged {w , map when jnanaged) 
Widget w; 

Boolean map jvhe'n jnanaged ; 
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w 



Specifies the widget. 



map jvhen jnanaged Specifies a Boolean value that indicates the new value of the 
map_when_managed field. 

If the widget is realized and managed and if the new value of map_when_managed is 
True, XtSetMappedWhenManaged maps the window. If the widget is realized and 
managed and if the new value of map_when_managed is False, it unmaps the window. 
XtSetMappedWhenManaged is a convenience function that is equivalent to (but slightly 
faster than) calling XtSetValues and setting the new value for the 
mappedWhenManaged resource. As an alternative to using 
XtSetMappedWhenManaged to control mapping, a client may set 
mapped_when_managed to False and use XtMapWidget and XtUnmapWidget 
explicitly. 

To map a widget explicitly, use XtMapWidget. 

XtMapWidget (w) 
Widget w; 

w Specifies the widget. 

To unmap a widget explicitly, use XtUnmapWidget. 

XtUnmapWidget (W) 
Widget w; 

w Specifies the widget. 



3.7 Constrained Composite Widgets 

Constraint widgets are a subclass of compos iteWidgetClass. Their name is 
derived from the fact that they may manage the geometry of their children based on 
constraints associated with each child. These constraints can be as simple as the maximum 
width and height the parent will allow the child to occupy or can be as complicated as how 
other children should change if this child is moved or resized. Constraint widgets let 
a parent define resources that are supplied for their children. For example, if the 
Constraint parent defines the maximum sizes for its children, these new size resources 
are retrieved for each child as if they were resources that were defined by the child widget. 
Accordingly, constraint resources may be included in the argument list or resource file just 
like any other resource for the child. 
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Constraint widgets have all the responsibilities of normal composite widgets and, in 
addition, must process and act upon the constraint information associated with each of 
their children. 

To make it easy for widgets and the X Toolkit Intrinsics to keep track of the constraints 
associated with a child, every widget has a constraints field, which is the address of a 
parent-specific structure that contains constraint information about the child. If a child's 
parent is not a subclass of constraintWidgetClass, then the child's constraints field 
is NULL. 

Subclasses of a Constraint widget can add additional constraint fields to their 
superclass. To allow this, widget writers should define the constraint records in their 
private .h file by using the same conventions as used for widget records. For example, a 
widget that needs to maintain a maximum width and height for each child might define its 
constraint record as follows: 

typedef struct { 

Dimension max_width, max_height; 
} MaxConstraintPart ; 

typedef struct { 

MaxConstraintPart max; 
} MaxConstraintRecord, *MaxConstraint ; 

A subclass of this widget that also needs to maintain a minimum size would define its 
constraint record as follows: 



typedef struct { 

Dimension min_width, min_height; 
} MinConstraintPart; 

typedef struct { 

MaxConstraintPart max; 

MinConstraintPart min; 
} MaxMinConstraintRecord, *MaxMinConstraint; 



Composite Widgets and Their Children 3-9 



Constraints are allocated, initialized, deallocated, and otherwise maintained insofar as 
possible by the X Toolkit Intrinsics . The constraint class record part has several entries 
that facilitate this. All entries in ConstraintClassPart are information and 
procedures that are defined and implemented by the parent, but they are called whenever 
actions are performed on the parent's children. 



The XtCreateWidget function uses the constraint_size field to allocate a constraint 
record when a child is created. The constraint_size field gives the number of bytes 
occupied by a constraint record. XtCreateWidget also uses the constraint resources 
to fill in resource fields in the constraint/record associated with a child. It then calls the 
constraint initialize procedure so that the parent can compute constraint fields that are 
derived from constraint resources and can possibly move or resize the child to conform to 
the given constraints. 

The XtGetValues and XtSejtVaixies functions use the constraint resources to get 
the values or set the valuesiof constraints associated with a child. XtSetValues then 
calls the constraint set^yalues procedures so that a parent can recompute derived 
constraint fields and move or resize the child as appropriate. 

The XtDestroyWidget function calls the constraint destroy procedure to deallocate 
any dynamic storage associated with a constraint record. The constraint record itself must 
not be deallocated by the constraint destroy procedure; XtDestroyWidget does this 
automatically. 
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Shell Widgets 
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Shell widgets hold an application's top-level widgets to allow them to communicate with 
the window manager. Shells have been designed to be as nearly invisible as possible. 
Clients have to create them, but they should never have to worry about their sizes. 

If a shell widget is resized from the outside (typically by a window manager), the shell 
widget also resizes its child widget automatically. Similarly, if the shell's child widget needs 
to change size, it can make a geometry request to the shell, and the shell negotiates the 
size change with the outer environment. Clients should never attempt to change the size of 
their shells directly. 

The four types of public shells are: 



Overr ideShell Used for shell windows that completely bypass the window manager (for 

example, pop-up menu shells). 

Trans i ent She 1 1 Used for shell windows that can be manipulated by the window manager 

but are not allowed to be iconified separately (for example, Dialog boxes 
that make no sense without their associated application). They are 
iconified by the window manager only if the main application shell is 
iconified. 



TopLevelShell Used for normal top-level windows (for example, any additional top-level 

widgets an application needs). 



ApplicationShell Used by the window manager to define a separate application instance, 

which is the main top-level window of the application. 
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4.1 Shell Widget Definitions 



Widgets negotiate their size and position with their parent widget, that is, the widget that 
directly contains them. Widgets at the top of the hierarchy do not have parent widgets. 
Instead, they must deal with the outside world. To provide for this, each top-level widget is 
encapsulated in a special widget, called a Shell. 

Shell widgets, a subclass of the Composite widget, encapsulate other widgets and can 
allow a widget to avoid the geometry clipping imposed by the parent/child window 
relationship. They also can provide a layer of communication with the window manager. 

The seven different types of shells are: 



Shell 

OverrideShell 

WMShell 

VendorShell 

Trans ientShell 

TopLevelShell 
ApplicationShell 



Provides the base class for shell widgets and the fields needed for all 
shells. Shell is a direct subclass of compos iteWidgetClass. 

Used for shell windows that completely bypass the window manager 
subclass of Shell. 

Contains fields needed by the common window manager protocol ar 
subclass of Shell. 

Contains fields used by vendor-specific window managers and is a su 
WMShell. 

Used for shell windows that can be manipulated by the window man; 
that are not allowed to be iconified and is a subclass of VendorSh* 

Used for normal top level windows and is a subclass of VendorShe 

Used for an application's top-level window and is a subclass of 
TopLevelShell. 



Note that the classes Shell, WMShell, and VendorShell are internal and should 
not be instantiated or subclassed. Only OverrrideShell, Trans ientShell, 
TopLevelShell, and ApplicationShell are for public use. 

4.1.1 ShellClassPart Definitions 

None of the shell widget classes has any additional fields: 

typedef struct { caddr_t extension; } ShellClassPart, OverrideShellClassPart, 
WMShellClassPart, VendorShellClassPart, TransientShellClassPart, 
TopLevelShellClassPart , ApplicationShellClassPart ; 
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Shell widget classes have the (empty) shell fields immediately following the composite 
fields: 



typedef struct _ShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

ShellClassPart shell_class; 
} ShellClassRec; 

typedef struct _OverrideShellClassRec { 
CoreClassPart core_class; 
CompositeClassPart composite_class ; 
ShellClassPart shell_class; 

OverrideShellClassPart override_shell_class ; 
} OverrideShellClassRec; 



typedef struct _WMShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

ShellClassPart shell_class; 

WMShellClassPart vmi_shell_class; 
} WMShellClassRec; 



typedef struct _VendorShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

ShellClassPart shell_class; 

WMShellClassPart wm_shell_class; 

VendorShellClassPart vendor_shell_class ; 
} VendorShellClassRec; 



typedef struct _TransientShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

ShellClassPart shell_class; 

WMShellClassPart wm_shell_class; 

VendorShellClassPart vendor_shell_class ; 

TransientShellClassPart transient_shell_class ; 
} TransientShellClassRec ; 



typedef struct _TopLevelShellClassRec { 

CoreClassPart core_class; 

CompositeClassPart composite_class ; 

ShellClassPart shell_class; 

WMShellClassPart vmi_shell_class; 

VendorShellClassPart vendor_shell_class ; 

TopLevelShellClassPart top_level_shell_class ; 
} TopLevelShellClassRec; 
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typedef struct _ApplicationSheLlClassRec { 

CoreClassPart core_class; 

CompositeClassFart composite_class ; 

ShellClassPart shell_class ; 

WMShellClassPart wm_shell_class ; 

VendorShellClassPart vendor_shell_class ; 

TopLevelShellClassPart top_level_shell_class ; 

ApplicationShellClassPart application_shell_class ; 
} ApplicationShellClassRec ; 

The predefined class records and pointers for shells are: 

extern ShellClassRec shellClassRec ; 

extern OverrideShellClassRec overrideShellClassRec ; 

extern WMShellClassRec wmShellClassRec ; 

extern VendorShellClassRec vendorShellClassRec ; 

extern TransientShellClassRec transientShellClassRec ; 

extern TopLevelShellClassRec topLevelShellClassRec; 

extern ApplicationShellClassRec applicationShellClassRec ; 

extern WidgetClass shellWidgetClass ; 
extern WidgetClass overrideShellWidgetClass ; 
extern WidgetClass wmShellWidgetClass; 
extern WidgetClass vendorShellWidgetClass; 
extern WidgetClass transientShellWidgetClass ; 
extern WidgetClass topLevelShellWidgetClass ; 
extern WidgetClass applicationShellWidgetClass; 

The following opaque types and opaque variables are defined for generic operations on 
widgets that are a subclass of ShellWidgetClass : 
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Types 



Variables 



ShellWidget 

OverrideShellWidget 

WMShellWidget 

VendorShellWidget 

TransientShellWidget 

TopLe ve 1 She 1 lWi dge t 

ApplicationShellWidget 

ShellWidgetClass 

OverrideShellWidgetClass 

WMShellWidgetClass 

VendorShellWidgetClass 

Trans ientShellWidgetClass 

TopLevelShellWidgetClass 

ApplicationShellWidgetClass 



ShellWidgetClass 

OverrideShellWidgetClass 

wmShellWidgetClass 

VendorShellWidgetClass 

transientShellWidgetClass 

t opLe ve 1 She 1 lWi dge t C las s 

applicationShellWidgetClass 



4.1.2 Shell Part Definition 

The various shells have the following additional fields defined in their widget records: 

typedef struct { 

String geometry; 

XtCreatePopupChildProc create_popup_child_proc ; 
XtGrabKind grab_kind; 
Boolean spring_loaded; 
Boolean popped_up; 
Boolean allow_shell_resize; 
Boolean client_specified; 
Boolean save_under; 
Boolean override_redirect; 
XtCallbackList popup_callback ; 
XtCallbackList popdown_callback; 
} ShellPart; 



typedef struct { int empty; } OverrideShellPart; 
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typedef struct { 

String title; 

int wm_timeout; 

Boolean wait_for_wm; 

Boolean transient; 

XSizeHints size_hints; 

XWMHints wm_hints; 
} WMShellPart; 

typedef struct { 

int vendor_specific ; 
} VendorShellPart; 



typedef struct { int empty; } TransientShellPart; 

typedef struct { 

String icon_name; 

Boolean iconic; 
} TopLevelShellPart; 



typedef struct { 

char *class; 

XrmClass xrm_class; 

int argc; 

char **argv; 
} ApplicationShellPart; 

The full definitions of the various shell widgets have shell fields following composite fields: 

typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 
} ShellRec, *ShellWidget; 

typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

OverrideShellPart override; 
} OverrideShellRec, *OverrideShellWidget; 



4-6 Shell Widgets 



typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 
} WMShellRec, *WMShellWidget; 

typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 
} VendorShellRec , *VendorShellWidget ; 



typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 

TransientShellPart transient; 
} TransientShellRec, *TransientShellWidget; 



typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 

TopLevelShellPart topLevel; 
} TopLevelShellRec , *TopLevelShellWidget; 



typedef struct { 

CorePart core; 

CompositePart composite; 

ShellPart shell; 

WMShellPart wm; 

VendorShellPart vendor; 

TopLevelShellPart topLevel; 

ApplicationShellPart application; 
} ApplicationShelLRec , *ApplicationShellWidget; 



4.1.3 ShellPart Default Values 

The default values for fields common to all classes of public shells (filled in by the Shell 
resource lists and the Shell initialize procedures) are: 
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Field 



Default Value 



geometry 

create_popup_child_proc 

grabjrind 

spring_loaded 

popped_up 

allow_shell_resize 

client_specified 

save_under 

override_redirect 

popup_callback 

popdown_callback 



NULL 

NULL 

(internal) 

(internal) 

(internal) 

False 

(internal) 

True for OverrideShell and 

Trans ientShell, False otherwise 

True for OverrideShell, False otherwise 

NULL 

NULL 



The geometry resource specifies the size and position and is usually done only from a 
command line or a defaults file. For further information, see Programming with Xlib . The 
create_popup_child_proc is called by the XtPopup procedure and is usually NULL. The 
allow_shell_resize field controls whether or not the widget contained by the shell is 
allowed to try to resize itself. If allow_shell_resize is False, any geometry requests 
always return XtGeometryNo. Setting save_under instructs the server to attempt to 
save the contents of windows obscured by the shell when it is mapped and to restore its 
contents automatically later. It is useful for pop-up menus. Setting overridejredirect 
determines whether or not the shell window is visible to the window manager. If it is 
True, the window is immediately mapped without the manager's intervention. The popup 
and popdown callbacks are called during XtPopup and Xt Pop down. For further 
information, see Programming with Xlib . 

The default values for shell fields in WMShell and its subclasses are: 
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Field 


Default Value 


title 


Icon name, if specified, otherwise the application's 




name 


wm timeout 


Five seconds 


wait_for_wm 


True 


transient 


True for Trans ientShell, False otherwise 


min width 


None 


min height 


None 


max_width 


None 


max height 


None 


width inc 


None 


height_inc 


None 


min_aspect x 


None 


min_aspect_y 


None 


max_aspect_x 


None 


max aspect y 


None 


input 


False 


initial_state 


Normal 


icon_pixmap 


None 


icon_window 


None 


icon x 


None 


icon_y 


None 


icon_mask 


None 


window_group 


None 



The title is a string to be displayed by the window manager. The wm_timeout resource 
limits the amount of time a shell is to wait for confirmation of a geometry request to the 
window manager. If none comes back within that time, the shell assumes the window 
manager is not functioning properly and sets wait_for_wm to be False (later events may 
reset this value). The wait_for_wm resource sets the initial state for this flag. When the 
flag is False, the shell does not wait for a response but relies on asynchronous 
notification. All other resources are for fields in the window manager hints and the 
window manager size hints. For further information, see Programming with Xlib and the 
Inter-Client Communcation Conventions Manual (Draft). 

TopLevel shells have the the following additional resources: 
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Field 


Default Value 


icon name 


Shell widget's name 


iconic 


False 



The icon_name field is the string to display in the shell's icon, and the iconic field is an 
alternative way to set the initialState resource to indicate that a shell should be initially 
displayed as an icon. 

Application shells have the following additional resources: 



Field 


Default Value 


argc 


0 


argv 


NULL 



The argc and argv fields are used to initialize the standard property WM COMMAND. See 
the Inter-Client Communcation Conventions Manual (Draft) for more information. 



4-10 Shell Widgets 



Pop-Up Widgets 



5 



Pop-up widgets are used to create windows that are outside of the window hierarchy 
defined by the widget tree. Each pop-up child has a window that is a descendant of the 
root window so that the pop-up window is not clipped by the pop-up widget's parent 
window. Therefore, pop-ups are created and attached differently to their widget parent 
than from normal widget children. 

A parent of a pop-up widget does not actively manage its pop-up children; in fact, it usually 
never notices them or operates upon them. The popup_list field in the CorePart 
structure contains the list of its pop-up children. This pop-up list exists mainly to provide 
the proper place in the widget hierarchy for the pop-up to get resources and to provide a 
place for XtDestroyWidget to look for all extant children. 

A Composite widget can have both normal and pop-up children. A pop-up can be 
popped up from almost anywhere, not just by its parent. A child always refers to a normal, 
geometry-managed child on the children list, and a pop-up child always refers to a child on 
the pop-up list. 



5.1 Pop-Up Widget Types 

There are three kinds of pop-up widgets: 

• Modeless pop-ups 

A modeless pop-up (for example, a modeless dialog box) is usually visible to the 
window manager and looks like any other application from the user's point of view. 
(The application itself is a special form of a modeless pop-up.) 

• Modal pop-ups 

A modal pop-up (for example, a modal dialog box) may or may not be visible to the 
window manager and, except for events that occur in the dialog box, disables user- 
event processing by the application. 

• Spring-loaded pop-ups 
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A spring-loaded pop-up (for example, a menu) is not visible to the window manager 
and, except for events that occur in the menu, disables user-event processing by all 
applications. 

Modal pop-ups and spring-loaded pop-ups are very similar and should be coded as if they 
are the same. In fact, the same widget (for examj ie, a ButtonBox or Menu) can be used 
both as a modal pop-up and as a spring-loaded pop-up within the same application. The 
main difference is that spring-loaded pop-ups are brought up with the pointer and, because 
of the grab that the pointer button causes, require different processing by the X Toolkit 
Intrinsics . Further, button up takes down a spring-loaded pop-up no matter where the 
button up occurs. 

Any kind of pop-up, in turn, can pop up other widgets. Modal and spring-loaded pop-ups 
can constrain user events to the most recent such pop-up or to any of the modal/spring- 
loaded pop-ups currently mapped. 

Regardless of their type, all pop-up widget classes are responsible for communicating with 
the X window manager and, therefore, are subclasses of Shell . 



5.2 Creating a Pop-Up Shell 

For a widget to pop up, it must be the child of a pop-up widget shell. A pop-up shell is 
never allowed more than one child, referred to as the pop-up child. Both the shell and 
child taken together are referred to as the pop-up. When you need to use a pop-up, you 
always should specify the pop-up shell, not the pop-up child. 

To create a pop-up shell, use XtCreatePopupShell. 

Widget XtCreatePopupShell (name, widget _class , parent, orgs, numjags) 
String name; 
WidgetClas s widget _class ; 
Widget parent; 
ArgList orgs; 
Cardinal numjags; 

name Specifies the text name for the created shell widget. 

widget _class Specifies the widget class pointer for the created shell widget. 

parent Specifies the parent widget. 

args Specifies the argument list to override the resource defaults. 

num jzrgs Specifies the number of arguments in the argument list. 
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The XtCreatePopupShell function ensures that the specified class is a subclass of 
Shell and, rather than using insert_child to attach the widget to the parent's children list, 
attaches the shell to the parent's pop-ups list directly. 

A spring-loaded pop-up invoked from a translation table already must exist at the time that 
the translation is invoked, so the translation manager can find the shell by name. Pop-ups 
invoked in other ways can be created "on-the-fly" when the pop-up actually is needed. 
This delayed creation of the shell is particularly useful when you pop up an unspecified 
number of pop-ups. You can look to see if an appropriate unused shell (that is, not 
currently popped up) exists and create a new shell if needed. 



5.3 Creating Pop-Up Children 

Once a pop-up shell is created, the single child of the pop-up shell can be created in one of 
two ways: 

• Static 

• Dynamic 

At startup, an application can create the child of the pop-up shell, which is appropriate for 
pop-up children that are composed of a fixed set of widgets. The application can change 
the state of the subparts of the pop-up child as the application state changes. For example, 
if an application creates a static menu, it can call XtSetSensitive (or, in general, 
XtSetValues) on any of the buttons that make up the menu. Creating the pop-up child 
early means that pop-up time is minimized, especially if the application calls 
XtRealizeWidget on the pop-up shell at startup. When the menu is needed, all the 
widgets that make up the menu already exist and need only be mapped. The menu should 
pop up as quickly as the X server can respond. 

Alternatively, an application can postpone the creation of the child until it is needed, which 
minimizes application startup time and allows the pop-up child to reconfigure itself each 
time it is popped up. In this case, the pop-up child creation routine should poll the 
application to find out if it should change the sensitivity of any of its subparts. 

Pop-up child creation does not map the pop-up, even if you create the child and call 
XtRealizeWidget on the pop-up shell. 

All shells have pop-up and pop-down callbacks, which provide the opportunity either to 
make last-minute changes to a pop-up child before it is popped up or to change it after it is 
popped down. Note that excessive use of pop-up callbacks can make popping up occur 
more slowly. 
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5.4 Mapping a Pop-Up Widget 

Pop-ups can be popped up through several mechanisms: 

• A call to XtPopup 

• One of the supplied callback procedures (for example, XtCallbackNone, 
XtCallbackNonexclusive, or XtCallbackExclusive) 

• The standard translation action MenuPopup 

Some of these routines take an argument of type XtGrabKind, which is defined as: 

typedef enum {XtGrabNone, XtGrabNonexclusive, XtGrabExclusive} XtGrabKind; 

To map a pop-up from within an application, use XtPopup . 

void XtPopup (popup jhell, grabjdnd) 
Widget popup jhell; 
XtGrabKind grabjdnd; 

popup jhell Specifies the widget shell. 

grabjcind Specifies the way in which user events should be constrained. 

The XtPopup function performs the following: 

• Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

• Generates an error if the shell's popped_up field is already True . 

• Calls the callback procedures on the shell's popup_callback list. 

• Sets the shell popped_up field to True , the shell spring_loaded field to False, 
and the shell grabjdnd field from grabjdnd. 

• If the shell's create_popup_child field is non-NULL, XtPopup calls it with 
popup_shell as the parameter. 

• If grabjdnd is either XtGrabNonexclusive or XtGrabExclusive, it calls: 

XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), False) 

• Calls XtRealizeWidget with popup_shell specified. 
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• Calls XMapWindow with popup_shell specified. 

To map a pop-up from a given widget's callback list, you also can use the 
XtCallbackNone, XtCallbackNonexclusive, or XtCallbackExclusive 
convenience routines. 

void XtCallbackNone (h>, client _data, catt_data) 
Widget w; 
caddr_t client _data; 
caddr_t call_data; 

w Specifies the widget. 

client _data Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 



void XtCallbackNonexclusive(H', client _data, call_data) 
Widget w; 
caddr_t client _data; 
caddr_t call_data; 

w Specifies the widget. 

client _data Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 



void XtCallbackExclusive(M>, client_data, calljlata) 
Widget W; 
caddr_t client _data; 
caddr_t call_data; 

w Specifies the widget. 

client Jiata Specifies the pop-up shell. 

call_data Specifies the callback data, which is not used by this procedure. 
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The XtCallbackNone, XtCallbackNonexclusive, and 

XtCallbackExclusive functions call XtPopup with the shell specified by the client 
data argument and grab_kind set as the name specifies. XtCallbackNone, 
XtCallbackNonexclusive, and XtCallbackExclusive specify XtGrabNone, 
XtGrabNonexclusive, and XtGrabExclusive, respectively. Each function then 
sets the widget that executed the callback list to be insensitive by using 
XtSetSensitive. Using these functions in callbacks is not required. In particular, an 
application must provide customized code for callbacks that create pop-up shells 
dynamically or that must do more than desensitizing the button. 

To pop up a menu when a pointer button is pressed or when the pointer is moved into 
some window, use MenuPopup . From a translation writer's point of view, the definition 
for this translation action is: 

void MenuPopup (shell jiame) 
String shell name ; 

shelljiame Specifies the name of the widget shell to pop up. 

MenuPopup is known to the translation manager, which must perform special actions for 
spring-loaded pop-ups. Calls to MenuPopup in a translation specification are mapped 
into calls to a nonexported action procedure, and the translation manager fills in 
parameters based on the event specified on the left-hand side of a translation. 

If MenuPopup is invoked on ButtonPress (possibly with modifiers), the translation 
manager pops up the shell with grab_kind set to XtGrabExclusive and spring_loaded 
set to True. If MenuPopup is invoked on EnterWindow (possibly with modifiers), 
the translation manager pops up the shell with grab_kind set to XtGrabNonexclusive 
and spring_loaded set to False. Otherwise, the translation manager generates an error. 
When the widget is popped up, the following actions occur: 

• Calls XtCheckSubc lass to ensure popup_shell is a subclass of Shell. 

• Generates an error if the shell's popped_up field is already True . 

• Calls the callback procedures on the shell's popup_callback list. 

• Sets the shell popped_up field to True and the shell grab_kind and spring_loaded 
fields appropriately. 

• If the shell's create_popup_child field is non-NULL, it is called with popup_shell as 
the parameter. 

• Calls: 

XtAddGrab(popup_shell, (grab_kind == XtGrabExclusive), spring_loaded) 



5-6 Pop-Up Widgets 



• Calls XtRealizeWidget with popup_shell specified. 

• Calls XMapWindow with popup_shell specified. 

(Note that these actions are the same as those for XtPopup .) MenuPopup tries to 
find the shell by searching the widget tree starting at the parent of the widget in which it is 
invoked. If it finds a shell with the specified name in the pop-up children of that parent, it 
pops up the shell with the appropriate parameters. Otherwise, it moves up the parent 
chain as needed. If MenuPopup gets to the application widget and cannot find a 
matching shell, it generates an error. 



5.5 Unmapping a Pop-Up Widget 

Pop-ups can be popped down through several mechanisms: 

• A call to XtPopdown 

• The supplied callback procedure XtCallbackPopdown 

• The standard translation action MenuPopdown 

To unmap a pop-up from within an application, use XtPopdown. 

void XtPopdown (/>opwp_5#e//) 
Widget popup jhell; 

popup jhell Specifies the widget shell to pop down. 
The XtPopdown function performs the following: 

• Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

• Checks that popup_shell is currently popped_up; otherwise, it generates an error. 

• Unmaps popup_shell's window. 

• If popup_shell's grab_kind is either XtGrabNonexclusive or 
XtGrabExclusive, it calls XtRemoveGrab. 

• Sets pop-up shell's popped_up field to False. 

• Calls the callback procedures on the shell's popdown_callback list. 

To pop down pop-up that have been popped up with one of the callback routines 
(XtCallbackNone, XtCallbackNonexclusive, XtCallbackExclusive), use 
the callback XtCallbackPopdown. 
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void XtCallbackPopdown(H\ client _data, call_data) 
Widget w; 
caddr_t client _data; 
caddr_t call_data; 

w Specifies the widget. 

client _data Specifies a pointer to the XtPopdownlD structure. 

call_data Specifies the callback data, which is not used by this procedure. 

The XtCallbackPopdown function casts the client data parameter to an 
XtPopdownlD pointer: 

typedef struct { 

Widget shell_widget; 

Widget enable_widget; 
} XtPopdownlDRec , *XtPopdownID; 

The shell_widget is the pop-up shell to pop down, and the enable_widget is the widget that 
was used to pop it up. 

XtCallbackPopdown calls XtPopdown with the specified shell_widget and then calls 
XtSetSensitive to resensitize the enable_widget. 

To pop down a spring-loaded menu when a pointer button is released or when the pointer 
is moved into some window, use MenuPopdown. From a translation writer's point of 
view, the definition for this translation action is: 

void MenuPopdovm(5^e//_na/ne) 
String shell jiame; 

shell jiame Specifies the name of the widget shell to pop down. 

If a shell name is not given, MenuPopdown calls XtPopdown with the widget for which 
the translation is specified. If a shell_name is specified in the translation table, 
MenuPopdown tries to find the shell by looking up the widget tree starting at the parent 
of the widget in which it is invoked. If it finds a shell with the specified name in the pop-up 
children of that parent, it pops down the shell; otherwise, it moves up the parent chain as 
needed. If MenuPopdown gets to the application top-level shell widget and cannot find a 
matching shell, it generates an error. 
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Geometry Management 
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A widget does not directly control its size and location; rather, its parent is responsible for 
controlling its size and location. Although the position of children is usually left up to then- 
parent, the widgets themselves often have the best idea of their optimal sizes and, possibly, 
preferred locations. 

To resolve physical layout conflicts between sibling widgets and between a widget and its 
parent, the X Toolkit Intrinsics provide the geometry management mechanism. Almost 
all Compos ite widgets have a geometry manager (geometry_manager field in the widget 
class record) that is responsible for the size, position, and stacking order of the widget's 
children. The only exception are fixed boxes, which create their children themselves and 
can ensure that their children will never make a geometry request. 



6.1 Initiating Geometry Changes 

Parents, children, and clients all initiate geometry changes differently. Because a parent 
has absolute control of its children's geometry, it changes the geometry directly by calling 
XtMoveWidget, XtResizeWidget, or XtConf igureWidget. A child must ask its 
parent for a geometry change by calling XtMakeGeometryRequest or 
XtMakeResizeRe quest to convey its wishes to its parent. An application or other 
client code initiates a geometry change by calling XtSetValues on the appropriate 
geometry fields, thereby giving the widget the opportunity to modify or reject the client 
request before it gets propagated to the parent and the opportunity to respond 
appropriately to the parent's reply. 

When a widget that needs to change its size, position, border width, or stacking depth asks 
its parent's geometry manager to make the desired changes, the geometry manager can do 
one of the following: 

• Allow the request 

• Disallow the request 

• Suggest a compromise 



Geometry Management 6-1 



When the geometry manager is asked to change the geometry of a child, the geometry 
manager may also rearrange and resize any or all of the other children that it controls. 
The geometry manager can move children around freely using XtMoveWidget. When it 
resizes a child (that is, changes width, height, or border_width) other than the one making 
the request, it should do so by calling XtResizeWidget. It can simultaneously move 
and resize a child with a single call to XtConf igureWidget. 

Often, geometry managers find that they can satisfy a request only if they can reconfigure 
a widget that they are not in control of (in particular, when the Compos ite widget wants 
to change its own size). In this case, the geometry manager makes a request to its parent's 
geometry manager. Geometry requests can cascade this way to arbitrary depth. 

Because such cascaded arbitration of widget geometry can involve extended negotiation, 
windows are not actually allocated to widgets at application startup until all widgets are 
satisfied with their geometry. For further information, see Sections 2.4 and 2.5. 



NOTE 

1. The X Toolkit Intrinsics treatment of stacking requests is 
deficient in several areas. Stacking requests for unrealized 
widgets are granted but will have no effect. In addition, there 
is no way to do an XtSetValues that will generate a 
stacking geometry request. 

2. After a successful geometry request (one that returned 
XtGeometryYes), a widget does not know whether or not its 
resize procedure has been called. Widgets should have resize 
procedures that can be called more than once without ill 
effects. 



6.2 General Geometry Manager Requests 

To make a general geometry manager request from a widget, use 
XtMakeGe ome t ryRe que s t . 

XtGeometryResult XtMakeGeometryRequest(K\ request, reply jeturn) 
Widget H>; 

XtWidgetGeometry *request; 
XtWidgetGeometry *reply jeturn • 
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w Specifies the widget that is making the request. 

request Specifies the desired widget geometry (size, position, border width, and 

stacking order). 

reply jetum Returns the allowed widget size or may be NULL if the requesting 
widget is not interested in handling XtGeometryAlmost. 

Depending on the condition, XtMakeGeometryRequest performs the following: 

• If the widget is unmanaged or the widget's parent is not realized, it makes the 
changes and returns XtGeometryYes. 

• If the parent is not a subclass of compositeWidgetClass or the parent's 
geometryjmanager is NULL, it issues an error. 

• If the widget's being_destroyed field is True, it returns XtGeometryNo. 

• If the widget x, y, width, height and border_width fields are all equal to the requested 
values, it returns XtGeometryYes ; otherwise, it calls the parent's 
geometry_manager procedure with the given parameters. 

• If the parent's geometry manager returns XtGeometryYes and if 
XtCWQueryOnly is not set in the request_mode and if the widget is realized, 
XtMakeGeometryRequest calls the XConf igureWindow Xlib function to 
reconfigure the widget's window (set its size, location, and stacking order as 
appropriate). 

• If the geometry manager returns XtGeometryDone, the change has been 
approved and p.ctually has been done. In this case, XtMakeGeometryRequest 
does no configuring and returns XtGeometryYes. 
XtMakeGeometryRequest never returns XtGeometryDone. 

Otherwise, XtMakeGeometryRequest returns the resulting value from the parent's 
geometry manager. 

Children of primitive widgets are always unmanaged; thus, XtMakeGeometryRequest 
always returns XtGeometryYes when called by a child of a primitive widget. 

The return codes from geometry managers are: 

typedef enum _XtGeometryResult { 

XtGeometryYes , 

XtGeometryNo , 

XtGeometryAlmost , 

XtGeometryDone 
} XtGeometryResult ; 
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The XtWidgetGeometry structure is quite similar but not identical to the 
corresponding Xlib structure: 

typedef unsigned long XtGeometryMask ; 

typedef struct { 

XtGeometryMask request_mode; 

Position x, y; 

Dimension width, height; 

Dimension border_width; 

Widget sibling; 

int stackjmode; 
} XtWidgetGeometry; 

The request_mode definitions are from < Xll/X . h > : 



#define 


cwx 


(1<<0) 


#define 


CWY 


(1<<1) 


#define 


CWWidth 


(1«2) 


#define 


CWHeight 


(1<<3) 


#define 


CWBorderWidth 


(1<<4) 


#define 


CWSibling 


(1<<5) 


#define 


CWStackMode 


(1<<6) 



The X Toolkit Intrinsics also support the following value: 

#define XtCWQueryOnly (1<<7) 

XtCWQueryOnly indicates that the corresponding geometry request is only a query as to 
what would happen if this geometry request were made and that no widgets should actually 
be changed. 

XtMakeGeometryRequest, like the XConf igureWindow Xlib function, uses 
request_mode to determine which fields in the XtWidgetGeometry structure you want 
to specify. 

The stack_mode definitions are from < Xll/X . h > : 



#define 


Above 


0 


#define 


Below 


1 


#define 


Top If 


2 


#define 


Bottomlf 


3 


#define 


Opposite 


4 
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The X Toolkit Intrinsics also support the following value: 
#define XtSMDontChange 5 

For definition and behavior of Above, Below, Toplf, Bottomlf , and Opposite, 
see Programming with Xlib . XtSMDontChange indicates that the widget wants its 
current stacking order preserved. 



6.3 Resize Requests 

To make a simple resize request from a widget, you can use XtMakeResizeRequest 
as an alternative to XtMakeGeometryRequest. 

XtGeometryResult XtMakeResizeRequest (w, width, height, width jeturn, height jeturn) 
Widget w; 

Dimension width, height; 

Dimension *width return, *height jeturn 

w Specifies the widget. 

width 

height Specify the desired widget width and height. 

width jeturn 

height jeturn Return the allowed widget width and height. 
The XtMakeResizeRequest function, a simple interface to 

XtMakeGeometryRequest, creates a XtWidgetGeometry structure and specifies 
that width and height should change. The geometry manager is free to modify any of the 
other window attributes (position or stacking order) to satisfy the resize request. If the 
return value is XtGeometryAlmost, width_return and height_return contain a 
compromise width and height. If these are acceptable, the widget should immediately 
make an XtMakeResizeRequest and request that the compromise width and height 
be applied. If the widget is not interested in XtGeometryAlmost replies, it can pass 
NULL for width_return and height_return. 
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6.4 Potential Geometry Changes 



Sometimes a geometry manager cannot respond to a geometry request from a child 
without first making a geometry request to the widget's own parent (the requestor's 
grandparent). If the request to the grandparent would allow the parent to satisfy the 
original request, the geometry manager can make the intermediate geometry request as if 
it were the originator. On the other hand, if the geometry manager already has 
determined that the original request cannot be completely satisfied (for example, if it 
always denies position changes), it needs to tell the grandparent to respond to the 
intermediate request without actually changing the geometry because it does not know if 
the child will accept the compromise. To accomplish this, the geometry manager uses 
XtCWQueryOnly in the intermediate request. 

When XtCWQueryOnly is used, the geometry manager needs to cache enough 
information to exactly reconstruct the intermediate request. If the grandparent's response 
to the intermediate query was XtGeometryAlmos t, the geometry manager needs to 
cache the entire reply geometry in the event the child accepts the parent's compromise. 

If the grandparent's response was XtGeometryAlmost, it may also be necessary to 
cache the entire reply geometry from the grandparent when XtCWQueryOnly is not 
used. If the geometry manager is still able to satisfy the original request, it may 
immediately accept the grandparent's compromise and then act on the child's request. If 
the grandparent's compromise geometry is insufficient to allow the child's request and if 
the geometry manager is willing to offer a different compromise to the child, the 
grandparent's compromise should not be accepted until the child has accepted the new 
compromise. 

Note that a compromise geometry returned with XtGeometryAlmost is guaranteed 
only for the next call to the same widget; therefore, a cache of size one is sufficient. 



6.5 Child Geometry Management 

The geometry_manager procedure pointer in a composite widget class is of type 
X t G e ome t r yHandl e r : 

typedef XtGeometryResult (*XtGeometryHandler ) (Widget, XtWidgetGeometry *, XtWidgetGeometry *] 
Widget w; 

XtWidgetGeometry *request; 
XtWidgetGeometry * 'geometry return; 

A class can inherit its superclass's geometry manager during class initialization. 
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A bit set to zero in the request's mask field means that the child widget does not care 
about the value of the corresponding field. Then, the geometry manager can change it as 
it wishes. A bit set to 1 means that the child wants that geometry element changed to the 
value in the corresponding field. 

If the geometry manager can satisfy all changes requested and if XtCWQueryOnly is not 
specified, it updates the widget's x, y, width, height, and border_width values appropriately. 
Then, it returns XtGeometryYes, and the value of the geometry_return argument is 
undefined. The widget's window is moved and resized automatically by 
XtMakeGeome t ryRe que s t . 

Homogeneous composite widgets often find it convenient to treat the widget making the 
request the same as any other widget, possibly reconfiguring it as part of its layout process, 
unless XtCWQueryOnly is specified. If it does this, it should return 
XtGeometryDone to inform XtMakeGeome tryRequest that it does not need to do 
the configuration itself. 

Although XtMakeGeome tryRequest resizes the widget's window (if the geometry 
manager returns XtGeometryYes), it does not call the widget class's resize procedure. 
The requesting widget must perform whatever resizing calculations are needed explicitly. 

If the geometry manager chooses to disallow the request, the widget cannot change its 
geometry. The value of the geometry_return parameter is undefined, and the geometry 
manager returns XtGeometryNo. 

Sometimes the geometry manager cannot satisfy the request exactly, but it may be able to 
satisfy a similar request. That is, it could satisfy only a subset of the requests (for example, 
size but not position) or a lesser request (for example, it cannot make the child as big as 
the request but it can make the child bigger than its current size). In such cases, the 
geometry manager fills in geometry_return with the actual changes it is willing to make, 
including an appropriate mask, and returns XtGeometryAlmost. If a bit in 
geometry_return- > request_mode is zero, the geometry manager does not change the 
corresponding value if the geometry_return is used immediately in a new request. If a bit 
is one, the geometry manager does change that element to the corresponding value in 
geometry_return. More bits may be set in geometry_return than in the original request if 
the geometry manager intends to change other fields should the child accept the 
compromise. 

When XtGeometryAlmost is returned, the widget must decide if the compromise 
suggested in geometry_return is acceptable. If it is, the widget must not change its 
geometry directly; rather, it must make another call to XtMakeGeometryRequest. 
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If the next geometry request from this child uses the geometry_return box filled in by an 
XtGeometryAlmost return and if there have been no intervening geometry requests on 
either its parent or any of its other children, the geometry manager must grant the request, 
if possible. That is, if the child asks immediately with the returned geometry, it should get 
an answer of XtGeometryYes. However, the user's window manager may affect the 
final outcome. 

To return an XtGeometryYes , the geometry manager frequently rearranges the 
position of other managed children by calling XtMoveWidget. However, a few 
geometry managers may sometimes change the size of other managed children by calling 
XtResizeWidget or XtConf igureWidget. If XtCWQueryOnly is specified, the 
geometry manager must return how it would react to this geometry request without 
actually moving or resizing any widgets. 

Geometry managers must not assume that the request and geometry_return arguments 
point to independent storage. The caller is permitted to use the same field for both, and 
the geometry manager must allocate its own temporary storage, if necessary. 



6.6 Widget Placement and Sizing 

To move a sibling widget of the child making the geometry request, use XtMoveWidget. 

void XtMoveWidget (w, x, y) 
Widget W; 
Position X; 
Position y; 

w Specifies the widget. 
x 

y Specify the new widget x and y coordinates. 

The XtMoveWidget function returns immediately if the specified geometry fields are 
the same as the old values. Otherwise, XtMoveWidget writes the new x and y values 
into the widget and, if the widget is realized, issues an Xlib XMoveWindow call on the 
widget's window. 

To resize a sibling widget of the child making the geometry request, use 
XtResizeWidget. 

void XtResizeWidget(H\ width, height, border jvidth) 
Widget w, 
Dimension width; 
Dimension height; 
Dimension border width; 
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Specifies the widget. 



width 
height 

border jvidth Specify the new widget size. 

The XtResizeWidget function returns immediately if the specified geometry fields are 
the same as the old values. Otherwise, XtResizeWidget writes the new width, height, 
and border_width values into the widget and, if the widget is realized, issues an 
XConf igureWindow call on the widget's window. 

If the new width or height are different from the old values, XtResizeWidget calls the 
widget's resize procedure to notify it of the size change. 

To move and resize the sibling widget of the child making the geometry request, use 
XtConf igureWidget. 

void XtConfigureWidget(H\ x, y, width, height, border jvidth) 
Widget H>; 
Position X; 
Position y; 
Dimension width; 
Dimension height; 
Dimension border jvidth; 

w Specifies the widget. 

x 

y Specify the new widget x and y coordinates. 

width 
height 

border jvidth Specify the new widget size. 

The XtConf igureWidget function returns immediately if the specified geometry 
fields are the same as the old values. Otherwise, XtConf igureWidget writes the new 
x, y, width, height, and border_width values into the widget and, if the widget is realized, 
makes an Xlib XConf igureWindow call on the widget's window. 

If either the new width or height is different from its old value, XtConf igureWidget 
calls the widget's resize procedure to notify it of the size change; otherwise, it simply 
returns. 

To resize a child widget that already has the new values of its width, height, and border 
width fields, use XtResizeWindow. 
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void XtResizeWindowCH 1 ) 
Widget W; 

w Specifies the widget. 

The XtResizeWindow function calls the XConf igureWindow Xlib function to make 
the window of the specified widget match its width, height, and border width. This request 
is done unconditionally because there is no way to tell if these values match the current 
values. Note that the widget's resize procedure is not called. 

There are very few times to use XtRes izeWindow; instead, you should use 
XtResizeWidget. 



6.7 Preferred Geometry 

Some parents may be willing to adjust their layouts to accommodate the preferred 
geometries of their children. They can use XtQueryGeometry to obtain the preferred 
geometry and, as they see fit, can use or ignore any portion of the response. 

To query a child widget's preferred geometry, use XtQueryGeometry. 

XtGeometryResuit XtQueryGeometry (w, intended, preferred jeturn) 
Widget H>; 

XtWidgetGeometry *intended, *pref erred jeturn; 
w Specifies the widget. 

intended Specifies any changes the parent plans to make to the child's 

geometry or NULL. 

preferred jeturn Returns the child widget's preferred geometry. 

To discover a child's preferred geometry, the child's parent sets any changes that it intends 
to make to the child's geometry in the corresponding fields of the intended structure, sets 
the corresponding bits in intended. request_mode, and calls XtQueryGeometry. 

XtQueryGeometry clears all bits in the preferred_return- > requestjnode and checks 
the query_geometry field of the specified widget's class record. If query_geometry is not 
NULL, XtQueryGeometry calls the query_geometry procedure and passes as 
arguments the specified widget, intended, and preferred_return structures. If the intended 
argument is NULL, XtQueryGeometry replaces it with a pointer to an 
XtWidgetGeometry structure with requestjnode =0 before calling query_geometry. 

The query_geometry procedure pointer is of type XtGeometryHandler. 
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typedef XtGeometryResult (*XtGeometryHandler) (Widget, XtWidgetGeometry *, XtWidgetGeometry *); 
Widget W; 

XtWidgetGeometry ^request; 
XtWidgetGeometry * 'geometry return; 

The query_geometry procedure is expected to examine the bits set in 
request- >request_mode, evaluate the preferred geometry of the widget, and store the 
result in geometry_return (setting the bits in geometry_return->request_mode 
corresponding to those geometry fields that it cares about). If the proposed geometry 
change is acceptable without modification, the query_geometry procedure should return 
XtGeome tryYes . If at least one field in geometry_return is different from the 
corresponding field in request or if a bit was set in geometry_return that was not set in 
request, the query_geometry procedure should return XtGeome tryAlmost. If the 
preferred geometry is identical to the current geometry, the query_geometry procedure 
should return XtGeometryNo. 

After calling the query_geometry procedure or if the query_geometry field is NULL, 
XtQueryGeometry examines all the unset bits in geometry_return->request_mode and 
sets the corresponding fields in geometry_return to the current values from the widget 
instance. If CWStackMode is not set, the stack_mode field is set to 
XtSMDont Change . XtQueryGeometry returns the value returned by the 
query_geometry procedure or XtGeome tryYes if the query_geometry field is NULL. 

Therefore, the caller can interpret a return of XtGeome tryYes as not needing to 
evaluate the contents of reply and, more importantly, not needing to modify its layout 
plans. A return of XtGeometryAlmost means either that both the parent and the child 
expressed interest in at least one common field and the child's preference does not match 
the parent's intentions or that the child expressed interest in a field that the parent might 
need to consider. A return value of XtGeometryNo means that both the parent and the 
child expressed interest in a field and that the child suggests that the field's current value is 
its preferred value. In addition, whether or not the caller ignores the return value or the 
reply mask, it is guaranteed that the reply structure contains complete geometry 
information for the child. 

Parents are expected to call XtQueryGeometry in their layout routine and wherever 
other information is significant after change_managed has been called. The 
changed_managed procedure may assume that the child's current geometry is its preferred 
geometry. Thus, the child is still responsible for storing values into its own geometry 
during its initialize procedure. 
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6.8 Size Change Management 

A child can be resized by its parent at any time. Widgets usually need to know when they 
have changed size so that they can lay out their displayed data again to match the new size. 
When a parent resizes a child, it calls XtResizeWidget, which updates the geometry 
fields in the widget, configures the window if the widget is realized, and calls the child's 
resize procedure to notify the child. The resize procedure pointer is of type 
XtWidgetProc. 

If a class need not recalculate anything when a widget is resized, it can specify NULL for 
the resize field in its class record. This is an unusual case and should occur only for 
widgets with very trivial display semantics. The resize procedure takes a widget as its only 
argument. The x, y, width, height and border_width fields of the widget contain the new 
values. The resize procedure should recalculate the layout of internal data as needed. 
(For example, a centered Label in a window that changes size should recalculate the 
starting position of the text.) The widget must obey resize as a command and must not 
treat it as a request. A widget must not issue an XtMakeGeometryRequest or 
XtMakeResizeRequest call from its resize procedure. 
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Event Management 



7 



While X allows the reading and processing of events anywhere in an application, widgets in 
the X Toolkit neither directly read events nor grab the server or pointer. Widgets register 
procedures that are to be called when an event or class of events occurs in that widget. 

A typical application consists of startup code followed by an event loop that reads events 
and dispatches them by calling the procedures that widgets have registered. The default 
event loop provided by the X Toolkit Intrinsics is XtAppMainLoop . 

The event manager is a collection of functions to perform the following tasks: 

• Add or remove event sources other than X server events (in particular, timer 
interrupts and file input). 

• Query the status of event sources. 

• Add or remove procedures to be called when an event occurs for a particular widget. 

• Enable and disable the dispatching of user-initiated events (keyboard and pointer 
events) for a particular widget. 

• Constrain the dispatching of events to a cascade of pop-up widgets. 

• Call the appropriate set of procedures currently registered when an event is read. 

Most widgets do not need to call any of the event handler functions explicitly. The normal 
interface to X events is through the higher-level translation manager, which maps 
sequences of X events (with modifiers) into procedure calls. Applications rarely use any of 
the event manager routines besides XtAppMainLoop. 



7.1 Adding and Deleting Additional Event Sources 

While most applications are driven only by X events, some applications need to 
incorporate other sources of input into the X Toolkit event handling mechanism. The 
event manager provides routines to integrate notification of timer events and file data 
pending into this mechanism. 
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The next section describes functions that provide input gathering from files. The 
application registers the files with the X Toolkit Intrinsics read routine. When input is 
pending on one of the files, the registered callback procedures are invoked. 



7.1 .1 Adding and Removing Input Sources 

To register a new file as an input source for a given application, use XtAppAddlnput. 

Xtlnputld XtAppAddlnput (app_context , source, condition, proc, client _data) 
XtAppContext app_context; 
int source; 
caddr_t condition; 
XtlnputCallbackProc proc; 
caddr_t client _data; 



app_context Specifies the application context that identifies the application. 

source Specifies the source file descriptor on an operating system dependent 

device specification. 

condition Specifies the mask that indicates a read, write, or exception condition or 

some operating system dependent condition. 

proc Specifies the procedure that is to be called when input is available. 

client _data Specifies the argument that is to be passed to the specified procedure 
when input is available. 

The XtAppAddlnput function registers with the X Toolkit Intrinsics read routine a 
new source of events, which is usually file input but can also be file output. Note that file 
should be loosely interpreted to mean any sink or source of data. XtAppAddlnput 
also specifies the conditions under which the source can generate events. When input is 
pending on this source, the callback procedure is called. 

The legal values for the condition argument are operating-system dependent. The 
condition is some union of XtlnputReadMask, XtlnputWriteMask, and 
XtlnputExceptMask. 

Callback procedure pointers that are used when there are file events are of type 
XtlnputCallbackProc: 

typedef void (^XtlnputCallbackProc) (caddr_t, int *, Xtlnputld *); 
caddr_t client _data ; 
int *source; 
Xtlnputld *id; 

client jdata Specifies the client data that was registered for this procedure in 
XtAppAddlnput . 
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source Specifies the source file descriptor generating the event. 

id Specifies the ID returned from the corresponding XtAppAddlnput 

call. 

To discontinue a source of input, use XtRemove Input. 

void XtRemove Input {id) 
Xtlnputld id; 

id Specifies the ID returned from the corresponding XtAppAddlnput call. 

The XtRemove Input function causes the X Toolkit Intrinsics read routine to stop 
watching for input from the input source. 

7.1.2 Adding and Removing Timeouts 

The timeout facility notifies the application or the widget through a callback procedure 
that a specified time interval has elapsed. Timeout values are uniquely identified by an 
interval ID. 



To create a timeout value, use XtAppAddTimeOut. 

Xtlntervalld XtAppAddTimeOut {app _context , interval, proc, client _data) 
XtAppContext app_context ; 
unsigned long interval; 
XtTimerCallbackProc proc; 
caddr_t client data; 



app_context Specifies the application context for which the timer is to be set. 

interval Specifies the time interval in milliseconds. 

proc Specifies the procedure that is to be called when the time expires. 

client _data Specifies the argument that is to be passed to the specified procedure 
when it is called. 

The XtAppAddTimeOut function creates a timeout and returns an identifier for it. The 
timeout value is set to interval. The callback procedure is called when the time interval 
elapses, and then the timeout is removed. 

Callback procedure pointer that are used when timeouts expire are of type 
XtTimerCallbackProc: 
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typedef void (*XtTimerCallbackProc) (caddr_t, Xtlntervalld *); 
caddr_t client _data; 
Xtlntervalld *id; 

client Jiata Specifies the client data that was registered for this procedure in 
XtAppAddT imeOut . 

id Specifies the ID returned from the corresponding XtAppAddT ime Out 

call. 

To clear a timeout value, use XtRemoveTimeOut. 

vo i d XtRemoveT imeOut ( timer ) 
Xtlntervalld timer; 

timer Specifies the ID for the timeout request to be destroyed. 

The XtRemoveTimeOut function removes the timeout. Note that timeouts are 
automatically removed once they trigger. 



7.2 Constraining Events to a Cascade of Widgets 

Modal widgets are widgets that, except for the input directly to them, lock out user input to 
the application. 

When a modal menu or modal dialog box is popped up using XtPopup, user events 
(keyboard and pointer events) that occur outside the modal widget should be delivered to 
the modal widget or ignored. In no case will user events be delivered to a widget outside 
the modal widget. 

Menus can pop up submenus and dialog boxes can pop up further dialog boxes to create a 
pop-up cascade. In this case, user events may be delivered to one of several modal widgets 
in the cascade. 

Display-related events should be delivered outside the modal cascade so that expose events 
and the like keep the application's display up to date. Any event that occurs within the 
cascade is delivered as usual. The user events that are delivered to the most recent 
spring-loaded shell in the cascade when they occur outside the cascade are called remap 
events and are KeyPress, KeyRelease, ButtonPress, and But tonRe lease. 
The user events that are ignored when they occur outside the cascade are 
MotionNotify, EnterNotify, and LeaveNotify. All other events are delivered 
normally. 
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XtPopup uses the XtAddGrab and XtRemoveGrab functions to constrain user 
events to a modal cascade and subsequently to remove a grab when the modal widget goes 
away. Usually you should have no need to call them explicitly. 

To redirect user input to a modal widget, use XtAddGrab . 

void XtAddGrab (w, exclusive, spring loaded) 
Widget W; 
Boolean exclusive; 
Boolean spring loaded; 

w Specifies the widget to add to the modal cascade. 

exclusive Specifies whether user events should be dispatched exclusively to this 

widget or also to previous widgets in the cascade. 

springjoaded Specifies whether this widget was popped up because the user pressed 
a pointer button. 

The XtAddGrab function appends the widget (and associated parameters) to the modal 
cascade and checks that exclusive is True if springjoaded is True. If these are not 
True, XtAddGrab generates an error. 

The modal cascade is used by XtDispatchEvent when it tries to dispatch a user event. 
When at least one modal widget is in the widget cascade, XtDispatchEvent first 
determines if the event should be delivered. It starts at the most recent cascade entry and 
follows the cascade up to and including the most recent cascade entry added with the 
exclusive parameter True. 

This subset of the modal cascade along with all descendants of these widgets comprise the 
active subset. User events that occur outside the widgets in this subset are ignored or 
remapped. Modal menus with submenus generally add a submenu widget to the cascade 
with exclusive False. Modal dialog boxes that need to restrict user input to the most 
deeply nested dialog box add a subdialog widget to the cascade with exclusive True . 
User events that occur within the active subset are delivered to the appropriate widget, 
which is usually a child or further descendant of the modal widget. 

Regardless of where on the screen they occur, remap events are always delivered to the 
most recent widget in the active subset of the cascade that has springjbaded True, if any 
such widget exists. 

To remove the redirection of user input to a modal widget, use XtRemoveGrab . 

void XtRemoveGrab (H>) 
Widget W; 
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w Specifies the widget to remove from the modal cascade. 

The XtRemoveGrab function removes widgets from the modal cascade starting at the 
most recent widget up to and including the specified widget. It issues an error if the 
specified widget is not on the modal cascade. 



7.3 Focusing Events on a Child 

To redirect keyboard input to a child of a Composite widget without calling 
XSetlnputFocus, use XtSetKeyboardFocus. 

XtSetKeyboardFocus (.subtree , descendant ) 
Widget subtree, descendant; 

subtree Specifies the subtree of the hierarchy for which the keyboard focus is to be 

set. 

descendant Specifies either the widget in the subtree structure which is to receive the 
keyboard event, or None. Note that it is not an error to specify None 
when no input focus was previously set. 

If a future Key Press or KeyRe lease event occurs within the specif ied subtree, 
XtSetKeyboardFocus causes XtDispatchEvent to remap and send the event to 
the specified descendant widget. 

When there is no modal cascade, keyboard events can occur within a widget W in one of 
three ways: 

• W has the X input focus. 

• W has the keyboard focus of one of its ancestors, and the event occurs within the 
ancestor or one of the ancestor's descendants. 

• No ancestor of W has a descendant within the keyboard focus, and the pointer is 
within W. 

When there is a modal cascade, a widget W receives keyboard events if an ancestor of W is 
in the active subset of the modal cascade and one or more of the previous conditions is 
True. 

When subtree or one of its descendants acquires the X input focus or the pointer moves 
into the subtree such that keyboard events would now be delivered to subtree, a 
Focus In event is generated for the descendant if FocusNotify events have been 
selected by the descendant. Similarly, when W loses the X input focus or the keyboard 
focus for one of its ancestors, a Focus Out event is generated for descendant if 
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FocusNotify events have been selected by the descendant. 

The accept_focus procedure pointer is of type XtAcceptFocusProc: 

typedef Boolean (*XtAcceptFocusProc) (Widget, Time); 
Widget W; 
Time *Hme; 

w Specifies the widget. 

time Specifies the X time of the event causing the accept focus. 

Widgets that need the input focus can call XSetlnputFocus explicitly. To allow 
outside agents to cause a widget to get the input focus, every widget exports an 
accept_focus procedure. The widget returns whether it actually took the focus or not, so 
that the parent can give the focus to another widget. Widgets that need to know when they 
lose the input focus must use the Xlib focus notification mechanism explicitly (typically by 
specifying translations for Focus In and Focus Out events). Widgets that never want 
the input focus should set their accept_focus procedure pointer to NULL. 

To call a widget's accept_focus procedure, use XtCallAcceptFocus . 

Boolean XtCallAcceptFocus (w, time) 
Widget W; 
Time *time; 

w Specifies the widget. 

time Specifies the X time of the event that is causing the accept focus. 

The XtCallAcceptFocus function calls the specified widget's accept_focus procedure, 
passing it the specified widget and time, and returns what the accept_focus procedure 
returns. If accept_focus is NULL, XtCallAcceptFocus returns False. 



7.4 Querying Event Sources 

The event manager provides several functions to examine and read events (including file 
and timer events) that are in the queue. The next three functions handle X Toolkit 
Intrinsics equivalents of the XPending, XPeekEvent, and XNextEvent Xlib calls. 

To determine if there are any events on the input queue for a given application, use 
XtAppPending. 
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XtlnputMask XtAppPending (app_context ) 
XtAppContext appjontext; 

appjcontext Specifies the application context that identifies the application to check. 

The XtAppPending function returns a nonzero value if there are events pending from 
the X server, timer pending, or other input sources pending. The value returned is a bit 
mask that is the OR of XtlMXEvent, XtlMTimer, and XtlMAlternatelnput 
(see XtAppProcessEvent). If there are no events pending, XtAppPending flushes 
the output buffer and returns zero. 

To return the value from the head of a given application's input queue without removing 
input from the queue, use XtAppPeekEvent. 

Boolean XtAppPeekEvent (appjontext, event jeturn) 
XtAppContext appjontext; 
XEvent * event jeturn ; 

app_context Specifies the application context that identifies the application. 

event jeturn Returns the event information to the specified event structure. 

If there is an event in the queue, XtAppPeekEvent fills in the event and returns a 
nonzero value. If no X input is on the queue, XtAppPeekEvent flushes the output 
buffer and blocks until input is available (possibly calling some timeout callbacks in the 
process). If the input is an event, XtAppPeekEvent fills in the event and returns a 
nonzero value. Otherwise, the input is for an alternate input source, and 
XtAppPeekEvent returns zero. 

To return the value from the head of a given application's input queue, use 
XtAppNext Event . 

void XtAppNextEvent(ap/J context, event jeturn) 
XtAppContext appjontext; 
XEvent * event jeturn; 

appjontext Specifies the application context that identifies the application. 

event jeturn Returns the event information to the specified event structure. 

If no input is on the X input queue, XtAppNextEvent flushes the X output buffer and 
waits for an event while looking at the other input sources and timeout values and calling 
any callback procedures triggered by them. This wait time can be used for background 
processing (see Section 7.8). 
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7.5 Dispatching Events 



The X Toolkit Intrinsics provide functions that dispatch events to widgets or other 
application code. Every client interested in X events on a widget uses 
XtAddEventHandler to register which events it is interested in and a procedure (event 
handler) that is to be called when the event happens in that window. The translation 
manager automatically registers event handlers for widgets that use translation tables (see 
Chapter 10). 

Applications that need direct control of the processing of different types of input should 
use XtAppProcess Event. 

void XtAppProcessEvent(^/>_co«*etf, mask) 
XtAppContext app_context; 
XtlnputMask mask; 

app_context Specifies the application context that identifies the application for which 
to process input. 

mask Specifies what types of events to process. The mask is the bitwise 

inclusive OR of any combination of XtlMXEvent, XtlMTimer, and 
XtlMAlternatelnput. As a convenience, the X Toolkit defines the 
symbolic name XtlMAll to be the bitwise inclusive OR of all event 
types. 

The XtAppProcessEvent function processes one timer, alternate input, or X event. If 
there is nothing of the appropriate type to process, XtAppProcessEvent blocks until 
there is. If there is more than one type of thing available to process, it is undefined which 
will get processed. Usually, this procedure is not called by client applications (see 
XtAppMainLoop). XtAppProcessEvent processes timer events by calling any 
appropriate timer callbacks, alternate input by calling any appropriate alternate input 
callbacks, and X events by calling XtDispatchEvent. 

When an X event is received, it is passed to XtDispatchEvent, which calls the 
appropriate event handlers and passes them the widget, the event, and client-specific data 
registered with each procedure. If there are no handlers for that event registered, the 
event is ignored and the dispatcher simply returns. The order in which the handlers are 
called is undefined. 



Boolean XtDispatchEvent (.event) 
XEvent *event; 
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event Specifies a pointer to the event structure that is to be dispatched to the 
appropriate event handler. 

The XtDispatchEvent function sends those events to the event handler functions that 
have been previously registered with the dispatch routine. XtDispatchEvent returns 
True if it dispatched the event to some handler and False if it found no handler to 
dispatch the event to. The most common use of XtDispatchEvent is to dispatch 
events acquired with the XtAppNextEvent procedure. However, it also can be used to 
dispatch user-constructed events. XtDispatchEvent also is responsible for 
implementing the grab semantics for XtAddGr ab . 



7.6 The Application Input Loop 

To process input from a given application, use XtAppMainLoop. 

void XtAppMainLoop (,app_context) 
XtAppContext app_context; 

appjcontext Specifies the application context that identifies the application. 

The XtAppMainLoop function first reads the next incoming X event by calling 
XtAppNextEvent and then it dispatches the event to the appropriate registered 
procedure by calling XtDispatchEvent. This constitutes the main loop of X Toolkit 
applications, and, as such, it does not return. Applications are expected to exit in response 
to some user action. There is nothing special about XtAppMainLoop; it is simply an 
infinite loop that calls XtAppNextEvent and then XtDispatchEvent. 

Applications can provide their own version of this loop, which tests some global 
termination flag or tests that the number of top-level widgets is larger than zero before 
circling back to the call to XtAppNextEvent . 



7.7 Setting and Checking the Sensitivity State of a Widget 

Many widgets have a mode in which they assume a different appearance (for example, are 
greyed out or stippled), do not respond to user events, and become dormant. 

When dormant, a widget is considered to be insensitive. If a widget is insensitive, the 
Event Manager does not dispatch any events to the widget with an event type of 
KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, 
EnterNotify, LeaveNotify, Focusln, or FocusOut. 
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A widget can be insensitive because its sensitive field is False or because one of its 
parents is insensitive, and, thus, the widget's ancestor_sensitive field also is False. A 
widget can but does not need to distinguish these two cases visually. 

To set the sensitivity state of a widget, use Xt Set Sensitive. 

void XtSetSensitive (w, sensitive) 
Widget w; 
Boolean sensitive; 

w Specifies the widget. 

sensitive Specifies a Boolean value that indicates whether the widget should receive 
keyboard and pointer events. 

The XtSetSensitive function first calls XtSetValues on the current widget with 
an argument list specifying that the sensitive field should change to the new value. It then 
recursively propagates the new value down the managed children tree by calling 
XtSetValues on each child to set the ancestor_sensitive to the new value if the new 
values for sensitive and the child's ancestor_sensitive are not the same. 

XtSetSensitive calls XtSetValues to change sensitive and ancestorjsensitive. 
Therefore, when one of these changes, the widget's set_values procedure should take 
whatever display actions are needed (for example, greying out or stippling the widget). 

XtSetSensitive maintains the invariant that if parent has either sensitive or 
ancestor_sensitive False, then all children have ancestor_sensitive False. 

To check the current sensitivity state of a given widget (which is usually done by parents), 
use XtlsSensitive. 

Boolean XtlsSensitiveCw) 
Widget w; 

w Specifies the widget. 

The XtlsSensitive function returns True or False to indicate whether or not 
user input events are being dispatched. If both core.sensitive and core.ancestor_sensitive 
are True, XtlsSensitive returns True ; otherwise, it returns False. 
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7.8 Adding Background Work Procedures 



The X Toolkit Intrinsics have limited support for background processing. Because most 
applications spend most of their time waiting for input, you can register an idle-time work 
procedure that will be called when the toolkit would otherwise block in 
XtAppNextEvent or XtAppProcessEvent. Work procedure pointers are of type 
XtWorkProc: 

typedef Boolean (*XtWorkProc) (caddr_t) ; 
caddr_t client JLata; 

client _data Client data specified when the work proc was registered. 

This procedure returns True if it is done, that is, the work procedure should be removed. 
Work procedures should be very judicious about how much they do. If they run for more 
than a small part of a second, response time is likely to suffer. 

To register a work procedure for a given application, use XtAppAddWorkProc . 

XtWorkProcId XtAppAddWorkProc (app_context , proc, client _data) 
XtAppContext app_context; 
XtWorkProc proc; 
caddr_t client _data; 

app_context Specifies the application context that identifies the application. 

proc Specifies the procedure that is to be called when the application is idle. 

client _data Specifies the argument that is to be passed to the specified procedure 
when it is called. 

The XtAppAddWorkProc function adds the specified work procedure for the 
application identified by app_context. 

XtWorkProcId is an opaque unique identifier for this work procedure. Multiple work 
procedures can be registered, and the most recently added one is always the one that is 
called. However, if a work procedure adds another work procedure, the newly added one 
has lower priority than the current one. 

To remove a work procedure, either return True from the procedure when it is called or 
use XtRemoveWorkProc. 

void XtRemoveWorkProc (iVf) 
XtWorkProcId id; 
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id Specifies which work procedure to remove. 

The XtRemoveWorkProc function explicitly removes the specified background work 
procedure. 

7.9 X Event Filters 

The event manager provides filters that can be applied to X user events. The filters, which 
screen out events that are redundant or are temporarily unwanted, handle the following: 

• Pointer motion compression 

• Enter/leave compression 

• Exposure compression 



7.9.1 Pointer Motion Compression 

Widgets can have a hard time keeping up with pointer motion events. Further, they usually 
do not actually care about every motion event. To throw out redundant motion events, the 
widget class field compress_motion should be True . When a request for an event would 
return a motion event, the X Toolkit Intrinsics check if there are any other motion events 
immediately following the current one, and, if so, skip all but the last of them. 

7.9.2 Enter/Leave Compression 

To throw out pairs of enter and leave events that have no intervening events, as can happen 
when the user moves the pointer across a widget without stopping in it, the widget class 
field compress_enterleave should be True . These enter and leave events are not 
delivered to the client if they are found together in the input queue. 

7.9.3 Exposure Compression 

Many widgets prefer to process a series of exposure events as a single expose region rather 
than as individual rectangles. Widgets with complex displays might use the expose region 
as a clip list in a graphics context, and widgets with simple displays might ignore the region 
entirely and redisplay their whole window or might get the bounding box from the region 
and redisplay only that rectangle. 
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In either case, these widgets do not care about getting partial expose events. If the 
compress_exposure field in the widget class structure is True, the event manager calls 
the widget's expose procedure only once for each series of exposure events. In this case, 
all Expose events are accumulated into a region. When the final Expose event in a 
series (that is, the one with count zero) is received, the event manager replaces the 
rectangle in the event with the bounding box for the region and calls the widget's expose 
procedure, passing the modified exposure event and the region. (See Programming with 
Mb .) 

If compress_exposure is False, the event manager calls the widget's expose procedure 
for every exposure event, passing it the event and a region argument of NULL. 



7.10 Widget Exposure and Visibility 

Every primitive widget and some composite widgets display data on the screen by means of 
raw Xlib calls. Widgets cannot simply write to the screen and forget what they have done. 
They must keep enough state to redisplay the window or parts of it if a portion is obscured 
and then reexposed. 

7.1 0.1 Redisplay of a Widget 

The expose procedure pointer in a widget class is of type XtExposeProc: 

typedef void (*XtExposeProc ) (Widget, XEvent *, Region); 
Widget W; 
XEvent *event; 
Region region; 

w Specifies the widget instance requiring redisplay. 

event Specifies the exposure event giving the rectangle requiring redisplay. 

region Specifies the union of all rectangles in this exposure sequence. 

The redisplay of a widget upon exposure is the responsibility of the expose procedure in 
the widget's class record. If a widget has no display semantics, it can specify NULL for the 
expose field. Many composite widgets serve only as containers for their children and have 
no expose procedure. 



NOTE 

If the expose procedure is NULL, XtRealizeWidget fills in a 
default bit gravity of NorthWestGravity before it calls the 
widget's realize procedure. 



7-14 Event Management 



If the widget's compress_exposure class field is False (see Section 7.9.3), region always 
is NULL. If the widget's compress_exposure class field is True, the event contains the 
bounding box for region. 

A small simple widget (for example, Label) can ignore the bounding box information in 
the event and redisplay the entire window. A more complicated widget (for example, Text) 
can use the bounding box information to minimize the amount of calculation and redisplay 
it does. A very complex widget uses the region as a clip list in a GC and ignores the event 
information. The expose procedure is responsible for exposure of all superclass data as 
well as its own. 

However, it often is possible to anticipate the display needs of several levels of subclassing. 
For example, rather than separate display procedures for the widgets Label, Command, 
and Toggle, you could write a single display routine in Label that uses display state fields 
like the following: 

Boolean invert 
Boolean highlight 
Dimension highlight_width 

Label would have invert and highlight always False and highlight_width zero. 
Command would dynamically set highlight and highlight_width, but it would leave invert 
always False. Finally, Toggle would dynamically set all three. In this case, the expose 
procedures for Command and Toggle inherit their superclass's expose procedure. For 
further information, see Section 1.4.9. 

7.10.2 Widget Visibility 

Some widgets may use substantial computing resources to display data. However, this 
effort is wasted if the widget is not actually visible on the screen, that is, if the widget is 
obscured by another application or is iconified. 

The visible field in the Core widget structure provides a hint to the widget that it need 
not display data. This field is guaranteed True by the time an Expose event is 
processed if the widget is visible but is usually False if the widget is not visible. 

Widgets can use or ignore the visible hint. If they ignore it, they should have 
visible_interest in their widget class record set False. In such cases, the visible field is 
initialized True and never changes. If visible_interest is True, the event manager asks 
for VisibilityNotify events for the widget and updates the visible field accordingly. 



Event Management 7 - 15 



7.11 X Event Handlers 



Event handlers are procedures that are called when specified events occur in a widget. 
Most widgets need not use event handlers explicitly. Instead, they use the X Toolkit 
Intrinsics translation manager. Event handler procedure pointers are of the type 
XtEventHandler : 

typedef void ( *XtEventHandler ) (Widget, caddr_t, XEvent *); 
Widget w; 
caddr_t client _data; 
XEvent *event; 

w Specifies the widget for which to handle events. 

client _data Specifies the client specific information registered with the event handler, 
which is usually NULL if the event handler is registered by the widget 
itself. 

event Specifies the triggering event. 



7.1 1 .1 Event Handlers that Select Events 

To register an event handler procedure with the dispatch mechanism, use 
XtAddEventHandler. 

void XtAddEventHandler (w, eventjnask, nonmaskable, proc, client_data) 
Widget W; 

EventMask eventjnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client JLata; 



w Specifies the widget for which this event handler is being registered. 

eventjnask Specifies the event mask for which to call this procedure. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 
called on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotify). 

proc Specifies the procedure that is to be called. 

client _data Specifies additional data to be passed to the client's event handler. 
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The XtAddEventHandler function registers a procedure with the dispatch mechanism 
that is to be called when an event that matches the mask occurs on the specified widget. If 
the procedure is already registered with the same client_data, the specified mask is ORed 
into the existing mask. If the widget is realized, XtAddEventHandler calls 
XSelectlnput, if necessary. 



To remove a previously registered event handler, use XtRemoveEventHandler . 

void XtRemoveEventHandler (n\ event jnask, nonmaskable, proc, client _data) 
Widget W; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client _data\ 



w Specifies the widget for which this procedure is registered. 

event jnask Specifies the event mask for which to unregister this procedure. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 
removed on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotify). 

proc Specifies the procedure that is to be removed. 

client jiata Specifies the client data registered. 

The XtRemoveEventHandler function stops the specified procedure from receiving 
the specified events. The request is ignored if client_data does not match the value given 
in the call to XtAddEventHandler. If the widget is realized, 
XtRemoveEventHandler calls XSelectlnput, if necessary. If the specified 
procedure has not been registered or if it has been registered with a different value of 
client_data, XtRemoveEventHandler returns without reporting an error. 

To stop a procedure from receiving any events, which will remove it from the widget's 
event_table entirely, call XtRemoveEventHandler with an event_mask of 
XtAllEvents and with nonmaskable True. 



7.11.2 Event Handlers that Do Not Select Events 

On occasion, clients need to register an event handler procedure with the dispatch 
mechanism without causing the server to select for that event. To do this, use 
XtAddRawEventHandler. 
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void XtAddRawEventHandler(H\ event jnask, nonmaskable, proc, client data) 
Widget w; 

EventMask event mask ; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client _data; 



W 

event jnask 
nonmaskable 



proc 

client data 



Specifies the widget for which this event handler is being registered. 

Specifies the event mask for which to call this procedure. 

Specifies a Boolean value that indicates whether this procedure should be 
removed on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotify). 

Specifies the procedure that is to be registered. 

Specifies additional data to be passed to the client's event handler. 



The XtAddRawEventHandler function is similar to XtAddEventHandler except 
that it does not affect the widget's mask and never causes an XS elect Input for its 
events. Note that the widget might already have those mask bits set because of other 
nonraw event handlers registered on it. 



To remove a previously registered raw event handler, use 
X tRemo veRawEven tHandl e r . 

void XtRemoveRawEventHandler(H>, event jnask, nonmaskable, proc, client _data) 
Widget W; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client jJata; 



W 



event jnask 
nonmaskable 



proc 

client data 



Specifies the widget for which this procedure is registered. 

Specifies the event mask for which to unregister this procedure. 

Specifies a Boolean value that indicates whether this procedure should be 
removed on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionClear, SelectionRequest, SelectionNotify, 
ClientMessage, and MappingNotify). 

Specifies the procedure that is to be registered. 

Specifies the client data registered. 
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The XtRemoveRawEventHandler function stops the specified procedure from 
receiving the specified events. Because the procedure is a raw event handler, this does not 
affect the widget's mask and never causes a call on XSelectlnput. 

7.11.3 Current Event Mask 

To retrieve the event mask for a given widget, use XtBuildEventMask. 

EventMask XtBuildEventMask (H>) 
Widget W; 

w Specifies the widget. 

The XtBuildEventMask function returns the event mask representing the logical OR 
of all event masks for event handlers registered on the widget with 

XtAddEventHandler and all event translations, including accelerators, installed on the 
widget. This is the same event mask stored into the XSetWindowAt tributes 
structure by XtRealizeWidget and sent to the server when event handlers and 
translations are installed or removed on the realized widget. 



Event Management 7-19 



Callbacks 
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Applications and other widgets (clients) often need to register a procedure with a widget 
that gets called under certain conditions. For example, when a widget is destroyed, every 
procedure on the widget's destroy_callbacks list is called to notify clients of the widget's 
impending doom. 

Every widget has a destroy_callbacks list. Widgets can define additional callback lists as 
they see fit. For example, the Command widget has a callback list to notify clients when 
the button has been activated. 



8.1 Using Callback Procedure and Callback List 
Definitions 

Callback procedure fields for use in callback lists are of type XtCallbackProc: 

typedef void (*XtCallbackProc ) (Widget, caddr_t, caddr_t); 
Widget W; 
caddr_t client _data; 
caddr_t callJLata; 

w Specifies the widget for which the callback is registered. 

client _data Specifies the data that the widget should pass back to the client when the 
widget executes the client's callback procedure. 

call_data Specifies any callback-specific data the widget wants to pass to the client. 

For example, when Scrollbar executes its thumbChanged callback list, it 
passes the new position of the thumb. 

The client_data argument provides a way for the client registering the callback also to 
register client-specific data (for example, a pointer to additional information about the 
widget, a reason for invoking the callback, and so on). The client_data value should be 
NULL if all necessary information is in the widget. The call_data argument is a 
convenience to avoid having simple cases where the client could otherwise call 
XtGetValues or a widget-specific function to retrieve data from the widget. Widgets 
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should generally avoid putting complex state information in call_data. The client can use 
the more general data retrieval methods, if necessary. 

Whenever a client wants to pass a callback list as an argument in an XtCreateWidget, 
XtSetValues, or XtGetValues call, it should specify the address of a null-terminated 
array of type XtCallbackList: 

typedef struct { 

XtCallbackProc callback; 

caddr_t closure; 
} XtCallbackRec , *XtCallbackList; 

For example, the callback list for procedures A and B with client data clientDataA and 
clientDataB, respectively, is: 

static XtCallbackRec callbacks [] = { 
{A, (caddr_t) clientDataA}, 
{B, (caddr_t) clientDataB}, 
{(XtCallbackProc) NULL, (caddr_t) NULL} 

}; 

Although callback lists are passed by address in argument lists, the X Toolkit Intrinsics 
know about callback lists. Your widget initialize and set_values procedures should not 
allocate memory for the callback list. The X Toolkit Intrinsics automatically do this for 
you by using a different structure for their internal representation. 



8.2 Identifying Callback Lists 

Whenever a widget contains a callback list for use by clients, it also exports in its public .h 
file the resource name of the callback list. Applications and client widgets never access 
callback list fields directly. Instead, they always identify the desired callback list by using 
the exported resource name. All the callback manipulation functions described in this 
chapter check to see that the requested callback list is indeed implemented by the widget. 

For the X Toolkit Intrinsics to find and correctly handle callback lists, they should be 
declared with a resource type of XtRCallback. 



8.3 Adding Callback Procedures 

To add a callback procedure to a given widget's callback list, use XtAddCallback. 
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void XtAddCallback(M>, callback jtame, callback, client _data) 
Widget w, 

String callback jtame; 
XtCallbackProc callback', 
caddr_t client _data; 



w Specifies the widget. 

callback jiame Specifies the callback list to which the procedure is to be appended. 
callback Specifies the callback procedure. 

client jiata Specifies the argument that is to be passed to the specified procedure 

when it is invoked by XtCallCallbacks or NULL. 

A callback will be invoked as many times as it occurs in the callback list. 

To add a list of callback procedures to a given widget's callback list, use 
XtAddCallbacks. 

void XtAddCallbacks (w, callback jtame, callbacks) 
Widget W; 

String callback jtame; 
XtCallbackList callbacks; 



w Specifies the widget. 

callback jiame Specifies the callback list to which the procedure is to be appended. 

callbacks Specifies the null-terminated list of callback procedures and 

corresponding client data. 



8.4 Removing Callback Procedures 

To delete a callback procedure from a given widget's callback list, use 
XtRemoveCal lb ack . 

void XtRemoveCallback(M', callback jtame , callback, client jJata) 
Widget w; 

String callback jtame ; 
XtCallbackProc callback; 
caddr_t client jiata; 

w Specifies the widget. 

callback jiame Specifies the callback list from which the procedure is to be deleted. 
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callback Specifies the callback procedure. 

client _data Specifies the client data to match on the registered callback procedure. 

The XtRemoveCallback function removes a callback only if both the procedure and 
the client data match. 

To delete a list of callback procedures from a given widget's callback list, use 
XtRemoveCallbacks . 

void XtRemoveCallbacks (h>, callback jtame , callbacks) 
Widget W; 

String callback jtame; 
XtCallbackList callbacks; 

w Specifies the widget. 

callback jtame Specifies the callback list from which the procedures are to be deleted. 

callbacks Specifies the null-terminated list of callback procedures and 

corresponding client data. 

To delete all callback procedures from a given widget's callback list and free all storage 
associated with the callback list, use XtRemoveAllCallbacks. 

void XtRemoveAllCallbacks (w , callback jtame) 
Widget w; 

String callback jtame; 

w Specifies the widget. 

callback jiame Specifies the callback list to be removed. 



8.5 Executing Callback Procedures 

To execute the procedures in a given widget's callback list, use XtCallCallbacks . 

void XtCallCallbacks (h\ callback jtame , call jiata) 
Widget w; 

String callback jtame ; 
caddr_t calljiata; 



w Specifies the widget. 

callback jiame Specifies the callback list to be executed. 
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call_data Specifies a callback-list specific data value to pass to each of the 

callback procedure in the list. 

If no data is needed (for example, the commandActivated callback list in Command needs 
only to notify its clients that the button has been activated), the call_data argument can be 
NULL. The call_data argument is the actual data if only one (32-bit) longword is needed 
or is the address of the data if more than one word is needed. 



8.6 Checking the Status of a Callback List 

To find out the status of a given widget's callback list, use XtHasCallbacks . 

typedef enum {XtCallbackNoList , XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus ; 

XtCallbackStatus XtHasCallbacks (w , callback name) 
Widget W; 

String callback jiane; 

w Specifies the widget. 

callback jiame Specifies the callback list to be checked. 

The XtHasCallbacks function first checks to see if the widget has a callback list 
identified by callback_name. If the callback list does not exist, XtHasCallbacks 
returns XtCallbackNoList. If the callback list exists but is empty, it returns 
XtCallbackHasNone. If the callback list exists and has at least one callback registered, 
it returns XtCallbackHasSome. 
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A resource is a field in the widget record with a corresponding resource entry in the 
resource list of the widget or any of its superclasses. This means that the field is settable 
by XtCreateWidget (by naming the field in the argument list), by an entry in the 
default resource files (by using either the name or class), and by XtSe tValues . In 
addition, it is readable by XtGetValues . Not all fields in a widget record are resources. 
Some are for bookkeeping use by the generic routines (like managed and 
being_destroyed). Others can be for local bookkeeping, and still others are derived from 
resources (many graphics contexts and pixmaps). 

Writers of widgets need to obtain a large set of resources at widget creation time. Some of 
the resources come from the argument list supplied in the call to XtCreateWidget, 
some from the resource database, and some from the internal defaults specified for the 
widget. Resources are obtained first from the argument list, then from the resource 
database for all resources not specified in the argument list, and lastly from the internal 
default, if needed. 



9.1 Resource Lists 

A resource entry specifies a field in the widget, the textual name and class of the field that 
argument lists and external resource files use to refer to the field and a default value that 
the field should get if no value is specified. The declaration for the XtRe source 
structure is: 

typedef struct { 

String resource_name; 

String resource_class; 

String resource_type ; 

Cardinal resource_size; 

Cardinal resource_offset; 

String def ault_type ; 

caddr_t def ault_address ; 
} XtResource, *XtResourceList; 
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The rcsource_name field contains the name used by clients to access the field in the 
widget. By convention, it starts with a lowercase letter and is spelled identically to the field 
name, except all underscores (_) are deleted and the next letter is replaced by its 
uppercase counterpart. For example, the resource name for background_pixel becomes 
backgroundPixel. Widget header files typically contain a symbolic name for each resource 
name. All resource names, classes, and types used by the X Toolkit Intrinsics are named 
in < Xll/S tr ingDef s . h > . The X Toolkit Intrinsics symbolic resource names begin 
with XtN and are followed by the string name (for example, XtNbackgroundPixel for 
backgroundPixel) . 

A resource class provides two functions: 

• It isolates an application from different representations that widgets can use for a 
similar resource. 

• It lets you specify values for several actual resources with a single name. A resource 
class should be chosen to span a group of closely related fields. 

For example, a widget can have several pixel resources: background, foreground, border, 
block cursor, pointer cursor, and so on. Typically, the background defaults to white and 
everything else to black. The resource class for each of these resources in the resource list 
should be chosen so that it takes the minimal number of entries in the resource database 
to make background offwhite and everything else darkblue. 

In this case, the background pixel should have a resource class of Background and all 
the other pixel entries a resource class of Foreground. Then, the resource file needs 
only two lines to change all pixels to offwhite or darkblue: 

^Background: offwhite 
*Foreground: darkblue 

Similarly, a widget may have several resource fonts (such as normal and bold), but all fonts 
should have the class Font. Thus, changing all fonts simply requires only a single line in 
the default resource file: 

*Font: 6x13 

(6x13 would be a valid font only if there was a fonts . al ias file providing use of that 
name. Otherwise, the whole font specification must be used. See /flUsing the X Window 
System/fP for more information about fonts. 

By convention, resource classes are always spelled starting with a capital letter. Their 
symbolic names are preceded with XtC (for example, XtCBackground). 
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The rcsourcc_typc field is the physical representation type of the resource. By convention, 
it starts with an uppercase letter and is spelled identically to the type name of the field. 
The resource type is used when resources are fetched to convert from the resource 
database format (usually String) or the default resource format (almost anything, but often 
String) to the desired physical representation (see Section 9.6). The X Toolkit Intrinsics 
define the following resource types: 



Resource Type 


Structure or Field Type 


XtRAcceleratorTable 


XtAccelerators 


XtRBoolean 


Boolean 


XtRBool 


Bool 


XtRCallback 


XtCallbackList 


XtRColor 


XColor 


XtRCursor 


Cursor 


XtRDimension 


Dimension 


XtRDisplay 


Display* 


XtRFile 


FILE* 


XtRFloat 


float 


XtRFont 


Font 


XtRFont Struct 


XFontStruct * 


XtRFunction 


(*)() 


XtRInt 


int 


XtRPixel 


Pixel 


XtRPixmap 


Pixmap 


XtRPointer 


caddr t 


XtRPosition 


Position 


XtRShort 


short 


XtRString 


char* 


XtRTranslationTable 


XtTranslations 


XtRUns ignedChar 


unsigned char 


XtRWidget 


Widget 


XtRWindow 


Window 
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The resourcejsize field is the size of the physical representation in bytes; you should 
specify it as "sizeof(fy/?e)" so that the compiler fills in the value. The resource_offset field 
is the offset in bytes of the field within the widget. You should use the XtOf f set macro 
to retrieve this value. The default_type field is the representation type of the default 
resource value. If defaultjype is different from resource_type and the default_type is 
needed, the resource manager invokes a conversion procedure from defaultjype to 
resource_type. Whenever possible, the default type should be identical to the resource 
type in order to minimize widget creation time. However, there are sometimes no values 
of the type that the program can easily specify. In this case, it should be a value that the 
converter is guaranteed to work for (for example, XtDef aultForeground for a pixel 
resource). The default_address field is the address of the default resource value. The 
default is used if a resource is not specified in the argument list or in the resource database 
or if the conversion from the representation type stored in the resource database fails, 
which can happen for various reasons (for example, a misspelled entry in a resource file). 

Two special representation types (XtRImmediate and XtRCallProc) are usable only 
as default resource types. XtRImmediate indicates that the value in the 
default_address field is the actual value of the resource rather than the address of the 
value. The value must be in correct representation type for the resource. No conversion is 
possible since there is no source representation type. XtRCallProc indicates that the 
value in the default_address field is a procedure variable. This procedure is automatically 
invoked with the widget, resource_offset, and a pointer to the XrmValue in which to 
store the result and is an XtResourceDef aultProc: 

typedef void (*XtResourceDef aultProc) (Widget, int, XrmValue *) 
Widget W; 
int offset; 
XrmValue *value; 

w Specifies the widget whose resource is to be obtained. 

offset Specifies the offset of the field in the widget record. 
value Specifies the resource value to fill in. 

The XtResourceDef aultProc procedure should fill in the addr field of the value 
with a pointer to the default data in its correct type. 



NOTE 

The default_address field in the resource structure is declared as a 
caddr_t. On some machine architectures, this may be insufficient to 
hold procedure variables. 
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To get the resource list structure for a particular class, use XtGetResourceList: 



void XtGetResourceList {class, resources jeturn , numjesources jeturn); 
WidgetClass class; 
XtResourceList Resources jeturn; 
Cardinal *num jesources jeturn ; 



widget jzlass 



Specifies the widget class. 



resources return 



Specifies a pointer to where to store the returned resource list. 
The caller must free this storage using XtFree when done 
with it. 



num resources return 



Specifies a pointer to where to store the number of entries in 
the resource list. 



If it is called before the widget class is initialized (that is, before the first widget of that 
class has been created), XtGetResourceList returns the resource list as specified in 
the widget class record. If it is called after the widget class has been initialized, 
XtGetResourceList returns a merged resource list that contains the resources for all 
superclasses. 

The routines XtSetValues and XtGetValues also use the resource list to set and 
get widget state. For further information, see Sections 9.7.1 and 9.7.2. 

Here is an abbreviated version of the resource list in the Label widget: 

/* Resources specific to Label */ 
static XtResource resources [] = { 

{XtNforeground, XtCForeground, XtRPixel, sizeof (Pixel) , 

XtOffset(LabelWidget, label. foreground) , XtRString, XtDef aultForeground} , 

{XtNfont, XtCFont, XtRFontStruct, sizeof (XFontStruct *), 

XtOffset(LabelWidget, label. font) .XtRString, XtDef aultFont} , 

{XtNlabel, XtCLabel, XtRString, sizeof (String) , 

XtOffset(LabelWidget, label. label) , XtRString, NULL}, 



The complete resource name for a field of a widget instance is the concatenation of the 
application shell name (from XtAppCreateShell), the instance names of all the 
widget's parents up to the ApplicationShellWidget, the instance name of the 
widget itself, and the resource name of the specified field of the widget. Likewise, the full 
resource class of a field of a widget instance is the concatenation of the application class 
(from XtAppCreateShell), the widget class names of all the widget's parents up to 



} 
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the ApplicationShellWidget (not the superclasses), the widget class name of the 
widget itself, and the resource name of the specified field of the widget. 



9.2 Byte Offset Calculations 

To determine the byte offset of a field within a structure, use XtOf f set. 

Cardinal XtOf f set (pointer Jype , field jiame) 
Type pointer jype ; 
Field field jiame; 

pointer Jype Specifics a type that is declared as a pointer to the structure. 

field jiame Specifies the name of the field for which to calculate the byte offset. 

The XtOf f set macro is usually used to determine the offset of various resource fields 
from the beginning of a widget and can be used at compile time in static initializations. 



9.3 Superclass to Subclass Chaining of Resource Lists 

The XtCreateWidget function gets resources as a superclass-to-subclass operation. 
That is, the resources specified in Core resource list are fetched, then those in the 
subclass, and so on down to the resources specified for this widget's class. Within a class, 
resources are fetched in the order they are declared. 

In general, if a widget resource field is declared in a superclass, that field is included in the 
superclass's resource list and need not be included in the subclass's resource list. For 
example, the Core class contains a resource entry for background_pixel. Consequently, 
the implementation of Label need not also have a resource entry for background_pixel. 
However, a subclass, by specifying a resource entry for that field in its own resource list, 
can override the resource entry for any field declared in a superclass. This is most often 
done to override the defaults provided in the superclass with new ones. At class 
initialization time, resource lists for that class are scanned from the superclass down to the 
class to look for resources with the same offset. A matching resource in a subclass will be 
reordered to override the superclass entry. (A copy of the superclass resource list is made 
to avoid affecting other subclasses of the superclass.) 
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9.4 Subresources 



A widget does not do anything to get its own resources; instead, XtCreateWidget does 
this automatically before calling the class initialize procedure. 

Some widgets have subparts that are not widgets but for which the widget would like to 
fetch resources. For example, the Text widget fetches resources for its source and sink. 
Such widgets call XtGetSubresources to accomplish this. 

void XtGetSubresources (w, base, name, class, resources, numresources , orgs, numargs) 
Widget w; 
caddr_t base; 
String name; 
String class; 

XtResourceList resources; 
Cardinal num resources ; 
ArgList orgs; 
Cardinal numargs; 

w Specifies the widget that wants resources for a subpart. 

base Specifies the base address of the subpart data structure where the 

resources should be written. 

name Specifics the name of the subpart. 

class Specifies the class of the subpart. 

resources Specifies the resource list for the subpart. 

numjresources Specifies the number of resources in the resource list. 

args Specifies the argument list to override resources obtained from the 

resource database. 

num_args Specifies the number of arguments in the argument list. 

The XtGetSubresources function constructs a name/class list from the application 
name/class, the name/classes of all its ancestors, and the widget itself. Then, it appends to 
this list the name/class pair passed in. The resources are fetched from the argument list, 
the resource database, or the default values in the resource list. Then, they are copied into 
the subpart record. If args is NULL, num args must be zero. However, if num_args is 
zero, the argument list is not referenced. 
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9.5 Obtaining Application Resources 



To retrieve resources that are not specific to a widget but apply to the overall application, 
use XtGetApplicationResources. 

void XtGetApplicationResources (w, base, resources, numjesources , orgs, num_args) 
Widget W; 
caddr_t base; 
XtRe s our c eL i s t resources ; 
Cardinal numjesources; 
ArgList args; 
Cardinal numjtrgs; 

w Specifies the widget that identifies the resource database to search. 

(The database is that associated with the display for this widget.) 

base Specifies the base address of the subpart data structure where the 

resources should be written. 

resources Specifies the resource list for the subpart. 

numjesources Specifies the number of resources in the resource list. 

args Specifies the argument list to override resources obtained from the 

resource database. 

num_args Specifies the number of arguments in the argument list. 

The XtGetApplicationResources function first uses the passed widget, which is 
usually an application shell, to construct a resource name and class list, Then, it retrieves 
the resources from the argument list, the resource database, or the resource list default 
values. After adding base to each address, XtGetApplicationResources copies the 
resources into the address given in the resource list. If args is NULL, num_args must be 
zero. However, if num_args is zero, the argument list is not referenced. The portable way 
to specify application resources is to declare them as members of a structure and pass the 
address of the structure as the base argument. 



9.6 Resource Conversions 

The X Toolkit Intrinsics provide a mechanism for registering representation converters 
that are automatically invoked by the resource fetching routines. The X Toolkit Intrinsics 
additionally provide and registers several commonly used converters. This resource 
conversion mechanism serves several purposes: 
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• It permits user and application resource files to contain ASCII representations of 
nontextual values. 

• It allows textual or other representations of default resource values that are 
dependent on the display, screen, or color map, and thus must be computed at run 
time. 

• It caches all conversion source and result data. Conversions that require much 
computation or space (for example, string to translation table) or that require round 
trips to the server (for example, string to font or color) are performed only once. 

9.6.1 Predef ined Resource Converters 

The X Toolkit Intrinsics define all the representations used in the Core , Compos i te , 
Constraint, and Shell widgets. It registers the following resource converters: 

From XtRString to: 

XtRAc celeratorTable, XtRBoolean, XtRBool, XtRCursor, 
XtRDimension, XtRDisplay, XtRFile, XtRFloat, XtRFont, 
XtRFontStruct, XtRInt, XtRPixel, XtRPosition, XtRShort, 
XtRTranslationTable, and XtRUnsignedChar. 

From XtRColor, to: XtRPixel. 

From XRInt, to: 

XtRBoolean, XtRBool, XtRColor, XtRDimension, XtRFloat, 
XtRFont, XtRPixel, XtRPixmap, XtRPosition, XtRShort, and 
X tRUns i gne dChar . 

From XtRPixel, to: XtRColor. 

The string to pixel conversion has two predefined constants that are guaranteed to work 
and contrast with each other (XtDef aultFore ground and 
XtDef aultBackground). They evaluate the black and white pixel values of the 
widget's screen, respectively. For applications that run with reverse video, however, they 
evaluate the white and black pixel values of the widget's screen, respectively. Similarly, the 
string to font and font structure converters recognize the constant XtDef ault Font and 
evaluate this to the font in the screen's default graphics context. 
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9.6.2 New Resource Converters 



Type converters use pointers to XrmValue structures (defined in 
< Xll/Xresource . h >) for input and output values. 

typedef struct { 

unsigned int size; 

caddr_t addr; 
} XrmValue, *XrmValuePtr ; 

A resource converter procedure pointer is of type XtConverter: 

typedef void (*XtConverter ) (XrmValue *, Cardinal *, XrmValue *, XrmValue *); 
XrmValue *args; 
Cardinal *num_argp; 
XrmValue *from; 
XrmValue *tO; 

args Specifies a list of additional XrmValue arguments to the converter if 

additional context is needed to perform the conversion or NULL. For 
example, the string-to-font converter needs the widget's screen, or the string 
to pixel converter needs the widget's screen and color map. 

num_args Specifies the number of additional XrmValue arguments or zero. 

from Specifies the value to convert. 

to Specifies the descriptor to use to return the converted value. 

Type converters should perform the following actions: 

• Check to see that the number of arguments passed is correct. 

• Attempt the type conversion. 

• If successful, return a pointer to the data in the to parameter; otherwise, call 
XtWarningMsg and return without modifying the to argument. 

Most type converters just take the data described by the specified from argument and 
return data by writing into the specified to argument. A few need other information, 
which is available in the specified argument list. A type converter can invoke another type 
converter, which allows differing sources that may convert into a common intermediate 
result to make maximum use of the type converter cache. 

Note that the address written to- > addr cannot be that of a local variable of the converter 
because this is not valid after the converter returns. It should be a pointer to a static 
variable, as in the following example where screenColor is returned. 

The following is an example of a converter that takes a string and converts it to a Pixel: 
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static void CvtStringToPixel(args , num_args, fromVal, toVal) 
XrmValue *args; 
Cardinal *num_args ; 
XrmValue *fromVal; 
XrmValue *toVal; 



{ 



static XColor screenColor; 

XColor exactColor; 

Screen *screen; 

Colormap colormap; 
Status status; 

char message[1000] ; 

XrmQuark q ; 
String par ams [ 1 ] ; 

Cardinal num_params = 1; 

if (*num_args ! = 2) 

XtErrorMsgC'cvtStringToPixel" , "wrongParameters" , "XtToolkitError" , 
"String to pixel conversion needs screen and colormap arguments' 
(String *)NULL, (Cardinal *)NULL); 



screen = *((Screen **) args [0] . addr ) ; 
colormap = *( (Colormap *) args [1] . addr) ; 

LowerCase( (char *) fromVal->addr , message); 
q = XrmStringToQuark (message ) ; 



if (q == XtQExtdef aultbackground) { done (&screen->white_j?ixel, Pixel); return; } 
if (q == XtQExtdef aultf oreground) { done(&screen->black_pixel, Pixel); return; } 

if ((char) fromVal->addr [0] == '#' ) { /* some color rgb definition */ 

status = XParseColor (DisplayOf Screen (screen ) , colormap, (String) f romVal->addr , 
&screenColor ) ; 

if (status != 0) status = XAllocColor (DisplayOfScreen(screen) , colormap, &screenColor ) ; 

} else /* some color name */ 

status = XAllocNamedColor (DisplayOfScreen( screen) , colormap, (String) f romVal->addr , 
&screenColor , &exactColor ) ; 



if (status == 0) { 



par ams [0]=(String)fromVal->addr ; 

XtWarningMsg( "cvtStringToPixel" , "noColormap" , "XtToolkitError" , 

"Cannot allocate colormap entry for \"%s\"", params, &num_params ) ; 



} else { 



toVal->addr = (caddr_t)&screenColor. pixel; 
toVal->size = sizeof (Pixel) ; 

} 

}; 
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All type converters should define some set of conversion values that they are guaranteed to 
succeed on so these can be used in the resource defaults. This issue arises only with 
conversions, such as fonts and colors, where there is no string representation that all server 
implementations will necessarily recognize. For resources like these, the converter should 
define a symbolic constant (for example, XtDef a iltForeground, 
XtDef aultBackground, or XtDef aultFont). 

9.6.3 Issuing Conversion Warnings 

The XtStringConversionWarning function is a convenience routine for new 
resource converters that convert from strings. 

void XtStringConversionWarning {src, dstjype) 
String src, dstjype; 

src Specifies the string that could not be converted. 

dstjype Specifies the name of the type to which the string could not be converted. 

The XtS tr ingConver s ionWarning function issues a warning message with name 
"conversionError", type "string", class "XtToolkitError, and the default message string 
"Cannot convert Vc" to type dstjype". 

9.6.4 Registering a New Resource Converter 

To register a new converter, use XtAppAddConverter . 

void XtAppAddConverter (.app_context , fromjype, tojype, converter, convert _args , numargs) 
XtAppContext app_context; 
String fromjype; 
String tojype; 
XtConverter converter; 
XtConvertArgList convert jirgs ; 
Cardinal num args ; 



app context 


Specifies 


fromjype 


Specifies 


tojype 


Specifies 


converter 


Specifies 


convert jtrgs 


Specifies 




NULL. 


num args 


Specifies 



Specifies the number of additional arguments to the converter or zero. 
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If the same from_type and to_type are specified in two calls to XtAppAddConverter, 
the second call overrides the first. For the few type converters that need additional 
arguments, the X Toolkit Intrinsics conversion mechanism provides a method of specifying 
how these arguments should be computed. The enumerated type XtAddressMode and 
the structure XtConvertArgR.ee specify how each argument is derived. These are 
defined in < Xll/Convert . h > . 

typedef enum { 

/* address mode parameter representation */ 



XtAddress , 


/* 


address */ 




XtBaseOffset, 


/* 


offset */ 




Xt Immediate, 


/* 


constant */ 




XtResourceString , 


/* 


resource name 


string */ 


XtRe s our c eQuark 


/* 


resource name 


quark */ 



} XtAddressMode; 

typedef struct { 

XtAddressMode addressjmode; 

caddr_t address_id; 

Cardinal size; 
} XtConvertArgRec , *XtConvertArgList; 

The address_mode field specifies how the address_id field should be interpreted. 
XtAddress causes address_id to be interpreted as the address of the data. 
XtBaseOffset causes address_id to be interpreted as the offset from the widget base. 
Xtlmmediate causes address_id to be interpreted as a constant. 

XtResourceString causes address_id to be interpreted as the name of a resource that 
is to be converted into an offset from widget base. XtRe s our c eQuark is an internal 
compiled form of an XtResourceString. The size field specifies the length of the 
data in bytes. 

The following provides the code that was used to register the CvtStringToPixel routine 
shown earlier: 

static XtConvertArgRec colorConvertArgs [ ] = { 

{XtBaseOffset, (caddr_t) XtOff set (Widget, core. screen) , sizeof (Screen *)}, 
{XtBaseOffset, (caddr_t) XtOff set (Widget, core. colormap) , sizeof (Colormap) } 

}; 

XtAddConverter(XtRString, XtRPixel, CvtStringToPixel.-; 
colorConvertArgs, XtNumber (colorConvertArgs) ) ; 

The conversion argument descriptors colorConvertArgs and screenConvertArg are 
predefined. The screenConvertArg descriptor puts the widget's screen field into args[0]. 
The colorConvertArgs descriptor puts the widget's screen field into args[0], and the 
widget's colormap field into args[l]. 
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Conversion routines should not just put a descriptor for the address of the base of the 
widget into args[0], and use that in the routine. They should pass in the actual values that 
the conversion depends on. By keeping the dependencies of the conversion procedure 
specific, it is more likely that subsequent conversions will find what they need in the 
conversion cache. This way the cache is smaller and has fewer and more widely applicable 
entries. 



9.6.5 Resource Converter Invocation 

All resource-fetching routines (for example, XtGetSubresources, 
XtGetApplicationResources, and so on) call resource converters if the user 
specifies a resource that is a different representation from the desired representation or if 
the widget's default resource value representation is different from the desired 
representation. 

To invoke resource conversions, use XtConvert or XtDirectConvert. 

void XtConvert(w, fromjype, from, tojype, tojeturn) 
Widget W; 
String fromjype; 
XrmValuePtr from; 
String tojype; 
XrmValuePtr tojeturn; 

w Specifies the widget to use for additional arguments (if any are needed). 

fromjype Specifies the source type. 

from Specifies the value to be converted. 

to JyP e Specifies the destination type. 

to return Returns the converted value. 



void XtDirectConvert (converter, orgs, numjirgs, from, tojeturn) 
XtConverter converter; 
XrmValuePtr orgs; 
Cardinal numjirgs ; 
XrmValuePtr from; 
XrmValuePtr tojeturn ; 



converter Specifies the conversion procedure that is to be called. 

args Specifies the argument list that contains the additional arguments needed to 

perform the conversion (often NULL). 
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numjirgs Specifies the number of additional arguments (often zero). 
from Specifies the value to be converted. 

tojeturn Returns the converted value. 

The XtConvert function looks up the type converter registered to convert from_type to 
to_type, computes any additional arguments needed, and then calls XtDirectConvert. 
The XtDirectConvert function looks in the converter cache to see if this conversion 
procedure has been called with the specified arguments. If so, it returns a descriptor for 
information stored in the cache; otherwise, it calls the converter and enters the result in 
the cache. 

Before calling the specified converter, XtDirectConvert sets the return value size to 
zero and the return value address to NULL. To determine if the conversion was 
successful, the client should check tojreturn.address for non-NULL. 



9.7 Reading and Writing Widget State 

Any resource field in a widget can be read or written by a client. On a write operation, the 
widget decides what changes it will actually allow and updates all derived fields 
appropriately. 

9.7.1 Obtaining Widget State 

To retrieve the current value of a resource associated with a widget instance, use 
XtGetValues. 

void XtGetValues (w, orgs, numjirgs) 
Widget W; 
ArgList orgs; 
Cardinal numjirgs; 

w Specifies the widget. 

args Specifies the argument list of name/address pairs that contain the resource 

name and the address into which the resource value is to be stored. The 
resource names are widget-dependent. 

numjirgs Specifies the number of arguments in the argument list. 
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The XtGetValues function starts with the resources specified for the core widget fields 
and proceeds down the subclass chain to the widget. The value field of a passed argument 
list should contain the address into which to store the corresponding resource value. It is 
the caller's responsibility to allocate and deallocate this storage according to the size of the 
resource representation type used within the widget. 

If the widget's parent is a subclass of constraintWidgetClass, XtGetValues 
then fetches the values for any constraint resources requested. It starts with the constraint 
resources specified for constraintWidgetClass and proceeds down to the subclass 
chain to the parent's constraint resources. If the argument list contains a resource name 
that is not found in any of the resource lists searched, the value at the corresponding 
address is not modified. Finally, if the get_values_hook procedures are non-NULL, they 
are called in superclass-to-subclass order after all the resource values have been fetched by 
XtGetValues. This permits a subclass to provide nonwidget resource data to 
XtGetValues. 

Widget Subpart Resource Data 

Widgets that have subparts can return resource values from them for XtGetValues by 
supplying a get_values_hook procedure. The get values_hook procedure pointer is of type 
XtArgsProc: 

typedef void (*XtArgsProc) (Widget, ArgList, Cardinal *); 
Widget W; 
ArgList orgs; 
Cardinal *num _args ; 

w Specifies the widget whose nonwidget resource values are to be retrieved. 

args Specifies the argument list that was passed to XtCreateWidget. 

nwn_args Specifies the number of arguments in the argument list. 

The widget should call XtGet Sub values and pass in its subresource list and the arg 
and num_args parameters. 

Widget Subpart State 

To retrieve the current value of a nonwidget resource data associated with a widget 
instance, use XtGetSubvalues . For a discussion of nonwidget subclass resources, see 
Section 9.4. 

void XtGetSubvalues {base, resources, num resources , args, num_args) 
caddr_t base; 
XtResourceList resources ; 
Cardinal num jesources ; 
ArgList args; 
Cardinal num jugs ; 
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base Specifies the base address of the subpart data structure where the 

resources should be retrieved. 

resources Specifies the nonwidget resources list. 

num jesources Specifies the number of resources in the resource list. 

args Specifies the argument list of name/address pairs that contain the 

resource name and the address into which the resource value is to be 
stored. The arguments and values passed in are dependent on the 
subpart. The storage for argument values that are pointed to by the 
argument list must be deallocated by the application when no longer 
needed. 

numjirgs Specifies the number of arguments in the argument list. 

The XtGetSubvalues function obtains resource values from the structure identified by 
base. 

9.7.2 Setting Widget State 

To modify the current value of a resource associated with a widget instance, use 
XtSetValues. 

void XtSetValues (h\ args, numjirgs) 
Widget W; 
ArgList args; 
Cardinal numjirgs ; 

w Specifies the widget. 

args Specifies the argument list of name/value pairs that contain the resources to 

be modified and their new values. The resources and values passed are 
dependent on the widget being modified. 

numjirgs Specifies the number of arguments in the argument list. 

The XtSetValues function starts with the resources specified for the Core widget 
fields and proceeds down the subclass chain to the widget. At each stage, it writes the new 
value (if specified by one of the arguments) or the existing value (if no new value is 
specified) to a new widget data record. XtSetValues then calls the set_values 
procedures for the widget in superclass-to-subclass order. If the widget has any non- 
NULL set_values_hook fields, these are called immediately after the corresponding 
set_values procedure. This procedure permits subclasses to set nonwidget data for 
XtSetValues. 
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If the widget's parent is a subclass of constraintWidgetClass, XtSetValues 
also updates the widget's constraints. It starts with the constraint resources specified for 
constraintWidgetClass and proceeds down the subclass chain to the parent's class. 
At each stage, it writes the new value or the existing value to a new constraint record. It 
then calls the constraint set_values procedures from constraintWidgetClass down 
to the parent's class. The constraint set_values procedures are called with widget 
arguments, as for all set_values procedures, not just the constraint record arguments, so 
that they can make adjustments to the desired values based on full information about the 
widget. 

XtSetValues determines if a geometry request is needed by comparing the current 
widget to the new widget. If any geometry changes are required, it makes the request, and 
the geometry manager returns XtGeometryYes, XtGeometryAlmost, or 
XtGeometryNo. If XtGeometryYes, XtSetValues calls the widget's resize 
procedure. If XtGeometryNo, XtSetValues resets the geometry fields to their 
original values. If XtGeometryAlmost, XtSetValues calls the set_values_almost 
procedure, which determines what should be done and writes new values for the geometry 
fields into the new widget. XtSetValues then repeats this process, deciding once 
more whether the geometry manager should be called. 

Finally, if any of the set_values procedures returned True, XtSetValues causes the 
widget's expose procedure to be invoked by calling the Xlib XClearArea function on 
the widget's window. 

Widget State 

The set_values procedure pointer in a widget class is of type XtSetValuesFunc: 

typedef Boolean (*XtSetValuesFunc) (Widget, Widget, Widget); 
Widget current; 
Widget request; 
Widget new; 

current Specifies a copy of the widget as it was before the XtSetValues call. 

request Specifies a copy of the widget with all values changed as asked for by the 

XtSetValues call before any class set_values procedures have been called. 

new Specifies the widget with the new values that are actually allowed. 

The set_values procedure should recompute any field derived from resources that are 
changed (for example, many GCs depend on foreground and background). If no 
recomputation is necessary and if none of the resources specific to a subclass require the 
window to be redisplayed when their values are changed, you can specify NULL for the 
set values field in the class record. 
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Like the initialize procedure, set_values mostly deals only with the fields defined in the 
subclass, but it has to resolve conflicts with its superclass, especially conflicts over width 
and height. 

Sometimes a subclass may want to overwrite values filled in by its superclass. In particular, 
size calculations of a superclass are often incorrect for a subclass and in this case, the 
subclass must modify or recalculate fields declared and computed by its superclass. 

As an example, a subclass can visually surround its superclass display. In this case, the 
width and height calculated by the superclass set_values procedure are too small and need 
to be incremented by the size of the surround. The subclass needs to know if its 
superclass's size was calculated by the superclass or was specified explicitly. All widgets 
must place themselves into whatever size is explicitly given, but they should compute a 
reasonable size if no size is requested. How does a subclass know the difference between a 
specified size and a size computed by a superclass? 

The request and new parameters provide the necessary information. The request widget is 
the widget as originally requested. The new widget starts with the values in the request, 
but it has been updated by all superclass set_values procedures called so far. A subclass 
set_values procedure can compare these two to resolve any potential conflicts. 

In the above example, the subclass with the visual surround can see if the width and height 
in the request widget are zero. If so, it adds its surround size to the width and height fields 
in the new widget. If not, it must make do with the size originally specified. 

The new widget is the actual widget instance record. Therefore, the set_values procedure 
should do all its work on the new widget (the request widget should never be modified), 
and if it needs to call any routines that operate on a widget, it should specify new as the 
widget instance. 

The widget specified by new starts with the values of that specified by request but has been 
modified by any superclass set_values procedures. A widget need not refer to the request 
widget, unless it must resolve conflicts between the current and new widgets. Any changes 
that the widget needs to make, including geometry changes, should be made in the new 
widget. 

Finally, the set_values procedure must return a Boolean that indicates whether the widget 
needs to be redisplayed. Note that a change in the geometry fields alone does not require 
the set_values procedure to return True ; the X server will eventually generate an 
Expose event, if necessary. After calling all the set_values procedures, XtSetValues 
forces a redisplay by calling the Xlib XClearArea function if any of the set_values 
procedures returned True . Therefore, a set_values procedure should not try to do its 
own redisplaying. 
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Set_values procedures should not do any work in response to changes in geometry because 
XtSetValues eventually will perform a geometry request, and that request might be 
denied. If the widget actually changes size in response to a XtSetValues , its resize 
procedure are called. Widgets should do any geometry-related work in their resize 
procedure. 

Note that it is permissible to call XtSetValues before a widget is realized. Therefore, 
the set_values proc must not assume that the widget is realized. 

Widget State 

The set_values_almost procedure pointer in a widget class is of type XtAlmostProc: 

typedef void (*XtAlmostProc ) (Widget, Widget, XtWidgetGeometry *, XtWidgetGeometry *); 
Widget W; 

Widget new jvidget jeturn ; 
XtWidgetGeometry *request; 
XtWidgetGeometry *repty; 

w Specifies the widget on which the geometry change is requested. 

new _widget jetiirn Specifies the new widget into which the geometry changes are to 
be stored. 

request Specifies the original geometry request that was sent to the 

geometry manager that returned XtGeometryAlmost. 

reply Specifies the compromise geometry that was returned by the 

geometry manager that returned XtGeometryAlmost. 

Most classes inherit this operation from their superclass by specifying 
XtlnheritSetValuesAlmost in the class initialization. The Core 
set_values_almost procedure accepts the compromise suggested. 

The set_values_almost procedure is called when a client tries to set a widget's geometry by 
means of a call to XtSetValues, and the geometry manager cannot satisfy the request 
but instead returns XtGeometryAlmost and a compromise geometry. The 
set_values_almost procedure takes the original geometry and the compromise geometry 
and determines whether the compromise is acceptable or a different compromise might 
work. It returns its results in the new_widget parameter, which is then sent back to the 
geometry manager for another try. 
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Widget State 

The constraint set_values procedure pointer is of type XtSetValuesFunc. The values 
passed to the parent's constraint set_values procedure are the same as those passed to the 
child's class set_values procedure. A class can specify NULL for the set_values field of the 
ConstraintPart if it need not compute anything. 

The constraint set_values procedure should recompute any constraint fields derived from 
constraint resource that are changed. Further, it should modify the widget fields as 
appropriate. For example, if a constraint for the maximum height of a widget is changed 
to a value smaller than the widget's current height, the constraint set_values procedure 
should reset the height field in the widget. 

Widget Subpart State 

To set the current value of a nonwidget resource associated with a widget instance, use 
XtSe tSub values . For a discussion of nonwidget subclass resources, see Section 9.4. 

void XtSetSubvalues(6ase, resources, numjesources , args, numjags) 
caddr_t base; 
XtResourceList resources ; 
Cardinal numjesources; 
ArgList orgs; 
Cardinal numjugs; 

base Specifies the base address of the subpart data structure where the 

resources should be written. 

resources Specifies the current nonwidget resources values. 

num resources Specifies the number of resources in the resource list. 

args Specifies the argument list of name/value pairs that contain the 

resources to be modified and their new values. The resources and 
values passed are dependent on the subpart of the widget being 
modified. 

num_args Specifies the number of arguments in the argument list. 

The XtSetSubvalues function stores resources into the structure identified by base. 

Widget Subpart Resource Data 

Widgets that have a subpart can set the resource values by using XtSetValues and 
supplying a set_values_hook procedure. The set_values_hook procedure pointer in a 
widget class is of type XtArgsFunc : 

typedef Boolean (*XtArgsFunc) (Widget, Arglist, Cardinal *); 
Widget w; 
ArgList args; 
Cardinal *num_args; 
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w Specifies the widget whose nonwidget resource values are to be changed. 

args Specifies the argument list that was passed to XtCreateWidget. 

num_args Specifies the number of arguments in the argument list. 
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Translation Management 



10 



Except under unusual circumstances, widgets do not hardwire the mapping of user events 
into widget behavior by using the event manager. Instead, they provide a default mapping 
of events into behavior that you can override. 

The translation manager provides an interface to specify and manage the mapping of X 
Event sequences into widget-supplied functionality, for example, calling procedure Abe 
when they key is pressed. 

The translation manager uses two kinds of tables to perform translations: 

• The action tables, which are in the widget class structure, specify the mapping of 
externally available procedure name strings to the corresponding procedure 
implemented by the widget class. 

• A translation table, which is in the widget class structure, specifies the mapping of 
event sequence to procedure name strings. 

You can override the translation table in the class structure for a specific widget instance 
by supplying a different translation table for the widget instance. The resource name is 
XtNtranslations. 



10.1 Action Tables 

All widget class records contain an action table. In addition, an application can register its 
own action tables with the translation manager so that the translation tables it provides to 
widget instances can access application functionality. The translation action_proc 
procedure pointer is of type XtAct ionProc : 

typedef void (*XtActionProc) (Widget, XEvent *, String *, Cardinal *); 
Widget W; 
XEvent *event; 
String *params; 
Cardinal *num _params; 

w Specifies the widget that caused the action to be called. 



Translation Management 10-1 



event Specifies the event that caused the action to be called. If the action is 

called after a sequence of events, then the last event in the sequence is 
used. 



params Specifies a pointer to the list of strings that were specified in the 

translation table as arguments to the action. 

num jparams Specifies the number of arguments specified in the translation table. 

typedef struct _XtActionsRec { 

String action_name; 

XtActionProc action_proc ; 
} XtActionsRec , *XtActionList; 

The action_name field is the name that you use in translation tables to access the 
procedure. The action_proc field is a pointer to a procedure that implements the 
functionality. 

For example, the Command widget has procedures to take the following actions: 

• Set the command button to indicate it is activated 

• Unset the button back to its normal mode 

• Highlight the button borders 

• Unhighlight the button borders 

• Notify any callbacks that the button has been activated 

The action table for the Command widget class makes these functions available to 
translation tables written for Command or any subclass. The string entry is the name used 
in translation tables. The procedure entry (often spelled identically to the string) is the 
name of the C procedure that implements that function: 

XtActionsRec actionTable[] = { 
{"Set", Set}, 
{"Unset", Unset}, 
{"Highlight" , Highlight} , 
{ "Unhighlight" , Unhighlight } 
{"Notify", Notify}, 

}; 

10.1.1 Action Table Registration 

To declare an action table and register it with the translation manager, use 
XtAppAddActions . 
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void XtAppAddActions (app _context , actions, numjictions) 
XtAppContext app_context; 
XtActionList actions; 
Cardinal numjictions ; 



num _args 



app_context 



actions 



Specifies the application context. 

Specifies the action table to register. 

Specifies the number of entries in this action table. 



If more than one action is registered with the same name, the most recently registered 
action is used. If duplicate actions exist in an action table, the first is used. The X Toolkit 
Intrinsics register an action table for MenuPopup and MenuPopdown as part of X 
Toolkit initialization. 

10.1.2 Action Names to Procedure Translations 

The translation manager uses a simple algorithm to convert the name of a procedure 
specified in a translation table into the actual procedure specified in an action table. 
When the widget is realized, the translation manager performs a search for the name in 
the following tables: 

• The widget's class action table for the name 

• The widget's superclass action table and on up the superclass chain 

• The action tables registered with XtAddActions (from the most recently added 
table to the oldest table) 

As soon as it finds a name, the translation manager stops the search. If it cannot find a 
name, the translation manager generates an error. 



All widget instance records contain a translation table, which is a resource with no default 
value. A translation table specifies what action procedures are invoked for an event or a 
sequence of events. A translation table is a string containing a list of translations from an 
event sequence into one or more action procedure calls. The translations are separated 
from one another by newline characters (ASCII LF). The complete syntax of translation 
tables is specified in Appendix B. 

As an example, the default behavior of Command is: 

• Highlight on enter window 

• Unhighlight on exit window 
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• Invert on button 1 down 

• Call callbacks and reinvert on button 1 up 

The following illustrates the Command's default translation table: 

static String def aultTranslations = 
"<EnterWindow> : Highlight ( ) \n\ 
<LeaveWindow>:Unhighlight( )\n\ 
<BtnlDown>: Set()\n\ 
<BtnlUp>: NotifyO UnsetO"; 

The tm_table field of the CoreClass record should be filled in at static initialization 
time with the string containing the class's default translations. If a class wants to inherit its 
superclass's translations, it can store the special value XtlnheritTranslations into 
tm_table. After the class initialization procedures have been called, the X Toolkit 
Intrinsics compile this translation table into an efficient internal form. Then, at widget 
creation time, this default translation table is used for any widgets that have not had then- 
core translations field set by the resource manager or the initialize procedures. 

The resource conversion mechanism automatically compiles string translation tables that 
are resources. If a client uses translation tables that are not resources, it must compile 
them itself using XtParseTranslatioriTable. 

The X Toolkit Intrinsics use the compiled form of the translation table to register the 
necessary events with the event manager. Widgets need do nothing other than specify the 
action and translation tables for events to be processed by the translation manager. 

10.2.1 Event Sequences 

An event sequence is a comma separated list of X event descriptions that describes a 
specific sequence of X events to map to a set of program actions. Each X event description 
consists of three parts: 

• The X event type 

• A prefix consisting of the X modifier bits 

• An event specific suffix 

Various abbreviations are supported to make translation tables easier to read. 
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10.2.2 Action Sequences 



Action sequences specify what program or widget actions to take in response to incoming 
X events. An action sequence of action procedure call specifications. Each action 
procedure call consists of the name of an action procedure and a parenthesized list of 
string parameters to pass to that procedure. 



10.3 Translation Table Management 

Sometimes an application needs to destructively or nondestructively add its own 
translations to a widget's translation. For example, a window manager provides functions 
to move a window. It usually may move the window when any pointer button is pressed 
down in a title bar, but it allows the user to specify other translations for buttons 2 or 3 
down in the title bar, and it ignores any user translations for button 1 down. 

To accomplish this, the window manager first should create the title bar and then should 
merge the two translation tables into the title bar's translations. One translation table 
contains the translations that the window manager wants only if the user has not specified 
a translation for a particular event (or event sequence). The other translation table 
contains the translations that the window manager wants regardless of what the user has 
specified. 

Three X Toolkit Intrinsics functions support this merging: 
XtParseTrans lat ionTable Compiles a translation table. 

XtAugmentTrans lat ions Nondestructively merges a compiled translation table into a 

widget's compiled translation table. 

XtOverrideTranslations Destructively merges a compiled translation table into a widget 

compiled translation table. 



To compile a translation table, use XtParseTranslat ionTable. 

XtTranslations XtParseTranslationTable(taZ)/e) 
String table; 

table Specifies the translation table to compile. 
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The XtParseTranslationTable function compiles the translation table into the 
opaque internal representation of type XtTranslations . Note that if an empty 
translation table is required for any purpose, one can be obtained by calling 
XtParseTranslationTable and passing an empty string. 

To merge new translations into an existing translation table, use 
XtAugmentTranslations . 

void XtAugmentTranslations (w, translations) 
Widget w; 

XtTranslations translations; 

w Specifies the widget into which the new translations are to be merged. 

translations Specifies the compiled translation table to merge in (must not be 
NULL). 

The XtAugmentTranslations function nondestructively merges the new translations 
into the existing widget translations. If the new translations contain an event or event 
sequence that already exists in the widget's translations, the new translation is ignored. 

To overwrite existing translations with new translations, use 
XtOverrideTranslations. 

void XtOverrideTranslations (h>, translations) 
Widget w; 

XtTranslations translations; 

w Specifies the widget into which the new translations are to be merged. 

translations Specifies the compiled translation table to merge in (must not be 
NULL). 

The XtOverrideTranslations function destructively merges the new translations 
into the existing widget translations. If the new translations contain an event or event 
sequence that already exists in the widget's translations, the new translation is merged in 
and override the widget's translation. 

To replace a widget's translations completely, use XtSetValues on the XtNtranslations 
resource and specifiy a compiled translation table as the value. 
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To make it possible for users to easily modify translation tables in their resource files, the 
string-to-translation-table resource type converter allows specifying whether the table 
should replace, augment, or override any existing translation table in the widget. As an 
option, you can specify a number sign (#) as the first character of the table followed by 
"replace" (default), "augment", or "override" to indicate whether to replace, augment, or 
override any existing table. 

To completely remove existing translations, use XtUnins tallTrans lat ions . 

void XtUninstallTranslations(H') 
Widget w; 

w Specifies the widget from which the translations are to be removed. 

The XtUninstallTranslations function causes the entire translation table for 
widget to be removed. 



10.4 Using Accelerators 

It is often convenient to be able to bind events in one widget to actions in another. In 
particular, it is often useful to be able to invoke menu actions from the keyboard. The X 
Toolkit Intrinsics provide a facility, called accelerators, that let you accomplish this. An 
accelerator is a translation table that is bound with its actions in the context of a particular 
widget. The accelerator table can then be installed on some destination widget. When an 
action in the destination widget would cause an accelerator action to be taken, rather than 
causing an action in the context of the destination, the actions are executed as though 
triggered by an action in the accelerator widget. 

Each widget instance contains that widget's exported accelerator table. Each class of 
widget exports a method that takes a displayable string representation of the accelerators 
so that widgets can display their current accelerators. The representation is the 
accelerator table in canonical translation table form (see Appendix B). The 
display_accelerator procedure pointer is of type XtStringProc: 

typedef void (*XtStringProc ) (Widget , String); 
Widget W; 
String string; 

w Specifies the widget that the accelerators are installed on. 

string Specifies the string representation of the accelerators for this widget. 
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Accelerators can be specified in defaults files, and the string representation is the same as 
for a translation table. However, the interpretation of the #augment and #override 
directives apply to what will happen when the accelerator is installed, that is, whether or 
not the accelerator translations will override the translations in the destination widget. 
The default is #augment, which means that the accelerator translations have lower priority 
than the destination translations. The #replace directive is ignored for accelerator tables. 

To parse an accelerator table, use XtParseAcceleratorTable. 

XtAccelerators XtParseAcceleratorTable (.source) 
String source; 

source Specifies the accelerator table to compile. 

The XtParseAcceleratorTable function compiles the accelerator table into the 
opaque internal representation. 

To install accelerators from a widget on another widget, use 
XtlnstallAccelerators . 

void XtlnstallAccelerators (.destination, source) 
Widget destination; 
Widget source; 

destination Specifies the widget on which the accelerators are to be installed. 

source Specifies the widget from which the accelerators are to come. 

The XtlnstallAccelerators function installs the accelerators from source onto 
destination by augmenting the destination translations with the source accelerators. If the 
source display_accelerator method is non-NULL, XtlnstallAccelerators calls it 
with the source widget and a string representation of the accelerator table, which indicates 
that its accelerators have been installed and that it should display them appropriately. The 
string representation of the accelerator table is its canonical translation table 
representation. 

As a convenience for installing all accelerators from a widget and all its descendants onto 
one destination, use XtlnstallAllAccelerators. 

void XtlnstallAllAccelerators (destination, source) 
Widget destination; 
Widget source; 

destination Specifies the widget on which the accelerators are to be installed. 
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source Specifies the root widget of the widget tree from which the accelerators 

are to come. 

The XtlnstallAllAccelerators function recursively descends the widget tree 
rooted at source and installs the accelerators of each widget encountered onto destination. 
A common use is to call XtlnstallAllAccelerators and pass the application main 
window as the source. 



10.5 KeyCode-to-KeySym Conversions 

The translation manager provides support for automatically translating key codes in 
incoming key events into KeySyms. KeyCode-to-KeySym-translator procedure pointers 
are of type XtKeyProc: 

typedef void (*XtKeyProc) (Display *, KeyCode, Modifiers, Modifiers *, KeySyra *); 
Display ^display; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers return; 
KeySym *keysym jeturn; 

display Specifies the display that the KeyCode is from. 

keycode Specifies the KeyCode to translate. 

modifiers Specifies the modifiers to the KeyCode. 

modifiers jeturn Returns a mask that indicates the subset of all modifiers that are 
examined by the key translator. 

key sym jeturn Returns the resulting KeySym. 

This procedure takes a KeyCode and modifiers and produces a KeySym. For any given 
key translator function, modifiers_return will be a constant that indicates the subset of all 
modifiers that are examined by the key translator. 

To register a key translator, use XtSetKeyTranslator . 

void XtSetKeyTranslator {display, proc) 
Display *display; 
XtKeyProc proc; 

display Specifies the display from which to translate the events. 
proc Specifies the procedure that is to perform key translations. 
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The XtSetKeyTranslator function sets the specified procedure as the current key 
translator. The default translator is XtTranslateKey, an XtKeyProc that uses Shift 
and Lock modifiers with the interpretations defined by the core protocol. It is provided so 
that new translators can call it to get default KeyCode-to-KeySym translations and so that 
the default translator can be reinstalled. 



To invoke the currently registered KeyCode-to-KeySym translator, use 
XtTranslateKeycode. 

void XtTranslateKeycode(disp/ay, keycode, modifiers, modifiers return , keysym return) 
Display ^display; 
KeyCode keycode; 
Modifiers modifiers; 
Modifiers *modifiers jetum ; 
KeySym *keysym_return ; 



Specifies the display that the KeyCode is from. 

Specifies the KeyCode to translate. 

Specifies the modifiers to the KeyCode. 

Returns a mask that indicates the modifiers actually used to 
generate the KeySym. 

Returns the resulting KeySym. 



display 
keycode 
modifiers 
modifiers jetum 

keysym return 

The XtTranslateKeycode function passes the specified arguments directly to the 
currently registered KeyCode to KeySym translator. 



To handle capitalization of nonstandard KeySyms, the X Toolkit Intrinsics allow clients to 
register case conversion routines. Case converter procedure pointers are of type 
XtCaseProc: 

typedef void (*XtCaseProc ) (KeySym *, KeySym *, KeySym *); 
KeySym *keysym; 
KeySym Hower return; 
KeySym *upperjeturn; 

keysym Specifies the KeySym to convert. 

lower jetum Specifies the lowercase equivalent for the KeySym. 

upper jetum Specifies the uppercase equivalent for the KeySym. 
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If there is no case distinction, this procedure should store the KeySym into both return 
values. 



To register a case converter, use XtRegisterCaseConverter. 

void XtRegisterCaseConverter (display, proc, start, stop) 
Display *display; 
XtCaseProc proc; 
KeySym start; 
KeySym stop; 

display Specifies the display from which the key events are to come. 

proc Specifies the XtCaseProc that is to do the conversions. 

start Specifies the first KeySym for which this converter is valid. 

stop Specifies the last KeySym for which this converter is valid. 

The XtRegisterCaseConverter registers the specified case converter. The start 
and stop arguments provide the inclusive range of KeySyms for which this converter is to 
be called. The new converter overrides any previous converters for KeySyms in that range. 
No interface exists to remove converters; you need to register an identity converter. When 
a new converter is registered, the X Toolkit Intrinsics refreshes the keyboard state if 
necessary. The default converter understands case conversion for all KeySyms defined in 
the core protocol. 

To determine upper and lowercase equivalents for a KeySym, use XtConver tCase . 

void XtConvertCase(d«p/oy, keysym, lower jeturn , upper return) 
Display *display; 
KeySym keysym; 
KeySym *lower jeturn; 
KeySym * upper jeturn ; 

display Specifies the display that the KeySym came from. 

keysym Specifies the KeySym to convert. 

lower jeturn Returns the lowercase equivalent of the KeySym. 

upper jeturn Returns the uppercase equivalent of the KeySym. 

The XtConver t Case function calls the appropriate converter and returns the results. 
A user-supplied XtKeyProc may need to use this function. 
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Utility Functions 
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The X Toolkit Intrinsics provide a number of utility functions that you can use to: 

• Determine the number of elements in an array 

• Translate strings to widget instances 

• Manage memory usage 

• Share graphics contexts 

• Manipulate selections 

• Merge exposure events into a region 

• Translate widget coordinates 

• Translate a window to a widget 

• Handle errors 



11.1 Determining the Number of Elements in an Array 

To determine the number of elements in a fixed-size array, use XtNumber. 

Cardinal XtNumber {array) 

ArrayVariable array; 

array Specifies a fixed-size array. 

The XtNumber macro returns the number of elements in the specified argument lists, 
resources lists, and other counted arrays. 
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1 1 .2 Translating Strings to Widget Instances 

To translate a widget name to widget instance, use XtNameToWidget. 

Widget XtNameToWidget {reference, names); 
Widget reference; 
String names; 

reference Specifies the widget from which the search is to start. 

names Specifies the fully qualified name of the desired widget. 

The XtNameToWidget function looks for a widget whose name is the first component in 
the specified names and that is a pop-up child of reference (or a normal child if reference 
is a subclass of compositeWidgetClass). It then uses that widget as the new 
reference and repeats the search after deleting the first component from the specified 
names. If it cannot find the specified widget, XtNameToWidget returns NULL. 

Note that the names argument contains the name of a widget with respect to the specified 
reference widget and can contain more than one widget name (separated by periods) for 
widgets that are not direct children of the specified reference widget. 

If more than one child of the reference widget matches the name, XtNameToWidget can 
return any of the children. The X Toolkit Intrinsics do not require that all children of a 
widget have unique names. If the specified names contain more than one component and 
if more than one child matches the first component, XtNameToWidget can return 
NULL if the single branch that it follows does not contain the named widget. That is, 
XtNameToWidget does not back up and follow other matching branches of the widget 
tree. 



11 .3 Managing Memory Usage 

The X Toolkit Intrinsics memory management functions provide uniform checking for null 
pointers and error reporting on memory allocation errors. These functions are completely 
compatible with their standard C language runtime counterparts (malloc, calloc, 
realloc, and free) with the following added functionality: 

• XtMalloc, XtCalloc,and XtRealloc give an error if there is not enough 
memory. 

• XtFree simply returns if passed a NULL pointer. 

• XtRealloc simply allocates new storage if passed a NULL pointer. 
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See the standard C library documentation on malloc, calloc, realloc,and 
free for more information. 

To allocate storage, use XtMalloc. 

char *XtMalloc(5<ze); 
Cardinal size; 

size Specifies the number of bytes desired. 

The XtMalloc functions returns a pointer to a block of storage of at least the specified 
size bytes. If there is insufficient memory to allocate the new block, XtMalloc calls 
XtErrorMsg. 

To allocate and initialize an array, use XtCalloc. 

char *XtCalloc (num, size); 
Cardinal num; 
Cardinal size; 

num Specifies the number of array elements to allocate. 
size Specifies the size of an array element in bytes. 

The XtCalloc function allocates space for the specified number of array elements of 
the specified size and initializes the space to zero. If there is insufficient memory to 
allocate the new block, XtCalloc calls XtErrorMsg. 

To change the size of an allocated block of storage, use XtRealloc . 

char *XtRealloc (ptr, num); 
char *ptr; 
Cardinal num; 

ptr Specifies a pointer to the old storage. 

num Specifies number of bytes desired in new storage. 

The XtRealloc function changes the size of a block of storage (possibly moving it). 
Then, it copies the old contents (or as much as will fit) into the new block and frees the old 
block. If there is insufficient memory to allocate the new block, XtRealloc calls 
XtErrorMsg. If ptr is NULL, XtRealloc allocates the new storage without copying 
the old contents; that is, it simply calls XtMalloc. 
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To free an allocated block of storage, use XtFr ee . 

void XtFree (ptr) ; 
char *ptr; 

ptr Specifies a pointer to the block of storage that is to be freed. 

The XtFree function returns storage and allows it to be reused. If ptr is NULL, 
XtFree returns immediately. 

To allocate storage for a new instance of a data type, use XtNew. 

type *XtNew(fy/>e) ; 
type; 

type Specifies a previously declared data type. 

XtNew returns a pointer to the allocated storage. If there is insufficient memory to 
allocate the new block, XtNew calls XtErrorMsg. XtNew is a convenience macro 
that calls XtMalloc with the following arguments specified: 

((type *) XtMalloc ( (unsigned) sizeof (type) ) 



To copy an instance of a string, use XtNewString. 

String XtNewString (string) ; 
String string; 

string Specifies a previously declared string. 

XtNewString returns a pointer to the allocated storage. If there is insufficient memory 
to allocate the new block, XtNewString calls XtErrorMsg. XtNewString is a 
convenience macro that calls XtMalloc with the following arguments specified: 

(strcpy (XtMalloc ( (unsigned) strlen(str) + 1), str)) 
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11.4 Sharing Graphics Contexts 



The X Toolkit Intrinsics provide a mechanism whereby cooperating clients can share a 
graphics context (GC), thereby reducing both the number of GCs created and the total 
number of server calls in any given application. The mechanism is a simple caching 
scheme, and all GCs obtained by means of this mechanism must be treated as read-only. 
If a changeable GC is needed, the Xlib XCreateGC function should be used instead. 

To obtain a read-only, sharable GC, use XtGetGC. 

GC XtGetGC (h>, value jnask, values) 
Widget W; 

XtGCMask value mask; 
XGCValues *vahtes; 

w Specifies the widget. 

value jnask Specifies which fields of the values are specified. 
values Specifies the actual values for this GC. 

The XtGetGC function returns a sharable, read-only GC. The parameters to this 
function are the same as those for XCreateGC except that a widget is passed instead of a 
display. XtGetGC shares only GCs in which all values in the GC returned by 
XCreateGC are the same. In particular, it does not use the value_mask provided to 
determine which fields of the GC a widget considers relevant. The value_mask is used 
only to tell the server which fields should be filled in with widget data and which it should 
fill in with default values. For further information about value_mask and values, see 
XCreateGC in the Programming with Xlib . 

To deallocate a shared GC when it is no longer needed, use XtReleaseGC. 

void XtReleaseGC (w, gc) 
Widget w; 
GC gc; 

w Specifies the widget. 

gc Specifies the GC to be deallocated. 

References to sharable GCs are counted and a free request is generated to the server 
when the last user of a given GC destroys it. 
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11 .5 Managing Selections 

Arbitrary widgets (possibly not all in the same application) can communicate with each 
other by means of the X Toolkit global selection mechanism, which is defined in the Inter- 
Client Communcation Conventions Manual (Draft). The X Toolkit Intrinsics provide 
functions for providing and receiving selection data in one logical piece (atomic transfers). 
The actual transfer between the selection owner and the X Toolkit Intrinsics is not 
required to be atomic; the X Toolkit Intrinsics will break a too-large selection into smaller 
pieces for transport if necessary. 

The next sections discuss how to: 

• Set and get the selection timeout value 

• Use atomic transfers 

1 1 .5.1 Setting and Getting the Selection Timeout Value 

To set the X Toolkit Intrinsics selection timeout, use XtAppSetSelectionTimeout. 

void XtAppSetSelectionTimeout (app_context , timeout) 
XtAppContext app_context; 
unsigned long timeout; 

app_context Specifies the application context. 

timeout Specifies the selection timeout in milliseconds. 

To get the current selection timeout value, use XtAppGetSelectionTimeout. 

unsigned long XtAppGetSelectionTimeout (app_context) 
XtAppContext app _context ; 

app_context Specifies the application context. 

The XtAppGetSelectionTimeout function returns the current selection timeout 
value, in milliseconds. The selection timeout is the time within which the two 
communicating applications must respond to one another. The initial timeout value is set 
by the selectionTimeout application resource, or, if selectionTimeout is not 
specified, it defaults to five seconds. 
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1 1 .5.2 Using Atomic Transfers 

The next three three sections discuss: 

• Atomic transfer procedures 

• Getting the selection value 

• Setting the selection owner 



Atomic Transfer Procedures 

The following procedures are to be used with atomic transfers. The first three are used by 
the selection owner, and the last one is used by the requestor. 



fcypedef Boolean (*XtConvertSelectionProc ) (Widget, Atom *, Atom *, Atom *, 
caddr_t *, unsigned long *, int *); 

Widget w; 
Atom *selection; 
Atom *target; 
Atom *type return; 
caddr_t *value return; 
unsigned long *length jeturn; 
int * format jeturn; 



w Specifies the widget which currently owns this selection. 

selection Specifies the atom that describes the type of selection requested (for 

example, XA_PRIMARY or XA_SECONDARY). 

target Specifies the target type of the selection that has been requested, which 

indicates the desired information about the selection (for example, File 
Name, Text, Window). 

type jeturn Specifies a pointer to an atom into which the property type of the 

converted value of the selection is to be stored. For instance, either file 
name or text might have property type XA_STRING . 

value jeturn Specifies a pointer into which a pointer to the converted value of the 

selection is to be stored. The selection owner is responsible for 
allocating this storage. If the selection owner has provided an 
XtSelectionDoneProc for the selection, this storage is owned by 
the selection owner; otherwise, it is owned by the X Toolkit Intrinsics 
selection mechanism, which frees it by calling XtFree when it is done 
with it. 

length jeturn Specifies a pointer into which the number of elements in value (each of 
size indicated by format) is to be stored. 
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format jeturn Specifies a pointer into which the size in bits of the data elements of 
the selection value is to be stored. 

This procedure is called by the X Toolkit Intrinsics selection mechanism to get the value 
of a selection as a given type from the current selection owner. It returns True if the 
owner successfully converted the selection to the target type or False otherwise. If the 
procedure returns False the values of the return arguments are undefined. Each 
XtConvertSelectionProc should respond to target value TARGETS by returning a 
value containing the list of the targets they are prepared to convert their selection into. 



typedef void (*XtLoseSelectionProc ) (Widget, Atom*); 
Widget W; 
Atom *selection; 

w Specifies the widget that has lost selection ownership. 

selection Specifies the atom that describes the selection type. 

This procedure is called by the X Toolkit Intrinsics selection mechanism to inform the 
specified widgets that it has lost the given selection. Note that this procedure does not ask 
the widget to lose the selection ownership. 



typedef void (*XtSelectionDoneProc ) (Widget, Atom *, Atom *); 
Widget w; 
Atom *selection; 
Atom *target; 

w Specifies the widget that owns the converted selection. 

selection Specifies the atom that describes the selection type that was converted. 

target Specifies the target type to which the conversion was done. 

This procedure is called by the X Toolkit Intrinsics selection mechanism to inform the 
selection owner when a selection requestor has successfully retrieved a selection value. If 
the selection owner has registered an XtSelectionDoneProc, it should expect it to be 
called once for each conversion that it performs but after the converted value has been 
successfully transferred to the requestor. If the selection owner has registered an 
XtSelectionDoneProc, it also owns the storage containing the converted selection 
value. 
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pedef void (*XtSelectionCallbackProc) (Widget, caddr_t, Atom *, Atom *, caddr_t, unsigned long *, int *); 
Widget w; 
caddr_t client Jlata; 
Atom *selection; 
Atom *type; 
caddr_t value; 
unsigned long *length; 
int * format; 

w Specifies the widget that requested the selection value. 

client jiata Specifies a value passed in by the widget when it requested the selection. 

selection Specifies the type of selection that was requested. 

type Specifies the representation type of the selection value (for example, 



XA_STRING). Note that it is not the target that was requested but the 
type that is used to represent the target. The special X Toolkit atom 
XT_CONVERT_FAIL is used to indicate that the selection conversion 
failed because the selection owner did not respond within the X Toolkit 
Intrinsics 's selection timeout interval. 



This procedure is called by the X Toolkit Intrinsics selection mechanism to deliver the 
requested selection to the requestor. 

Getting the Selection Value 

To obtain the selection value in a single, logical unit, use XtGetSelectionValue or 
XtGetSelectionValues . 

void XtGetSelectionValue (w , selection, target, callback, client_data, time) 
Widget W; 
Atom selection; 
Atom target; 

XtSelectionCallbackProc callback; 
caddr_t client _data; 
Time time; 

w Specifies the widget that is making the request. 

selection Specifies the particular selection desired (that is, primary or secondary). 

target Specifies the type of the information that is needed about the selection. 



value 



Specifies a pointer to the selection value. The requesting client owns this 
storage and is responsible for freeing it by calling XtFree when it is 
done with it. 



length 
format 



Specifies the number of elements in value. 

Specifies the size in bits of the data elements of value. 
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callback Specifies the callback procedure that is to be called when the selection 

value has been obtained. Note that this is how the selection value is 
communicated back to the client. 

client jdata Specifies the argument that is to be passed to the specified procedure 
when it is called. 

time Specifies the timestamp that indicates when the selection is desired. This 

should be the timestamp of the event which triggered this request; the 
value CurrentTime is not acceptable. 

The XtGetSelectionValue function requests the value of the selection that has been 
converted to the target type. The specified callback will be called some time after 
XtGetSelectionValue is called; in fact, it may be called before or after 
XtGetSelectionValue returns. 



void XtGetSelectionValues(H>, selection, targets, count, callback, client _data, time) 
Widget W; 
Atom selection; 
Atom *targets; 
int count; 

XtSelectionCallbackProc callback; 
caddr_t client jdata; 
Time time; 



W 

selection 
targets 
count 
callback 

clientjdata 
time 



Specifies the widget that is making the request. 

Specifies the particular selection desired (that is, primary or secondary). 

Specifies the types of information that is needed about the selection. 

Specifies the length of the targets and client_data lists. 

Specifies the callback procedure that is to be called with each selection 
value obtained. Note that this is how the selection values are 
communicated back to the client. 

Specifies the client data (one for each target type) that is passed to the 
callback procedure when it is called for that target. 

Specifies the timestamp that indicates when the selection value is desired. 
This should be the timestamp of the event which triggered this request; 
the value CurrentTime is not acceptable. 
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The XtGetSelectionValu.es function is similar to XtGetSelectionValue 
except that it takes a list of target types and a list of client data and obtains the current 
value of the selection converted to each of the targets. The effect is as if each target were 
specified in a separate call to XtGetSelectionValue. The callback is called once 
with the corresponding client data for each target. XtGetSelectionValues does 
guarantee that all the conversions will use the same selection value becaues the ownership 
of the selection cannot change in the middle of the list, as would be when calling 
XtGetSelectionValue repeatedly. 

Setting the Selection Owner 

To set the selection owner when using atomic transfers, use XtOwnS elect ion. 

Boolean XtOwnSelection(w, selection, time, convert j>roc, losejelection, donejyroc) 
Widget w; 
Atom selection; 
Time time; 

XtConvertSelectionProc convert _proc; 
XtLoseSelectionProc losejelection ; 
XtSelectionDoneProc done _proc; 



w Specifies the widget that wishes to become the owner. 

selection Specifies an atom that describes the type of the selection (for 

example, XA_PRIMARY, XA_SECONDARY, or XA_CLIPBOARD). 

time Specifies the timestamp that indicates when the selection ownership 

should commence. This should be the timestamp of the event that 
triggered ownership; the value CurrentTime is not acceptable. 

convert _proc Specifies the procedure that is to be called whenever someone 

requests the current value of the selection. 

losejelection Specifies the procedure that is to be called whenever the widget has 
lost selection ownership or NULL if the owner is not interested in 
being called back. 

done _proc Specifies the procedure that is called after the requestor has received 

the selection or NULL if the owner is not interested in being called 
back. 

The XtOwnS elect ion function informs the X Toolkit Intrinsics selection mechanism 
that a widget believes it owns a selection. It returns True if the widget has successfully 
become the owner and False otherwise. The widget may fail to become the owner if 
some other widget has asserted ownership at a time later than this widget. Note that 
widgets can lose selection ownership either because someone else asserted later ownership 
of the selection or because the widget voluntarily gave up ownership of the selection. Also 
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note that the lose_selection procedure is not called if the widget fails to obtain selection 
ownership in the first place. 

Usually, the X Toolkit Intrinsics selection mechanism informs an application when one of 
its widgets has lost ownership of the selection. However, in response to some user actions 
(for example, when a user deletes the information selected), the application should 
explicitly inform the X Toolkit Intrinsics that it's widget no longer is to be the selection 
owner by using XtDisownSelection. 

void XtDisownSelection(M', selection, time) 
Widget W; 
Atom selection; 
Time time; 

w Specifies the widget that wishes to relinquish ownership. 

selection Specifies the atom that specifies which selection it is giving up. 

time Specifies the timestamp that indicates when the selection ownership is 

relinquished. 

The XtDisownSelection function informs the X Toolkit Intrinsics selection 
mechanism that the specified widget is to lose ownership of the selection. If the widget 
does not currently own the selection either because it lost the selection or because it never 
had the selection to begin with, X t D i s ownS election does nothing. 

After a widget has called XtDisownSelection, its convert procedure is not called 
even if a request arrives later with a timestamp during the period that this widget owned 
the selection. However, its done procedure will be called if a conversion that started 
before the call to XtDisownSelection finishes after the call to 
XtDisownSelection. 



11 .6 Merging Exposure Events into a Region 

The X Toolkit Intrinsics provide the XtAddExposureToRegion utility function that 
merges Expose and GraphicsExpose events into a region that clients can process at 
once rather than processing individual rectangles. (For further information about regions, 
see Programming with Xlib .) 

To merge Expose and GraphicsExpose events into a region, use 
XtAddExposureToRegion. 
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void XtAddExposureToRegion (even* , region) 
XEvent *event; 
Region region; 

event Specifies a pointer to the Expose or GraphicsExpose event. 

region Specifies the region object (as defined in < Xll/Xutil . h > ). 

The XtAddExposureToRegion function computes the union of the rectangle defined 
by the exposure event and the specified region. Then, it stores the results back in region. 
If the event argument is not an Expose or GraphicsExpose event, 
XtAddExposureToRegion returns without an error and without modifying region. 

This function is used by the exposure compression mechanism (see Section 7.9.3). 



1 1 .7 Translating Widget Coordinates 

To translate an x-y coordinate pair from widget coordinates to root coordinates, use 
XtTranslateCoords. 

void XtTranslateCoords (m\ x, y, rootxjetum , rooty return) 
Widget w; 
Position x, y; 

Position *rootx return , *rooty return; 

w Specifies the widget. 
x 

y Specify the widget-relative x and y coordinates. 
rootxjetum 

rooty jeturn Returns the root-relative x and y coordinates. 

While XtTranslateCoords is similar to the Xlib XTranslateCoordinates 
function, it does not generate a server request because all the required information already 
is in the widget's data structures. 



11.8 Translating a Window to a Widget 

To translate a window and display pointer into a widget instance, use 
XtWindowToWidget. 

Widget XtWindowToWidget(<ftsp/ay, window) 
Display *display; 
Window window; 
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display Specifies the display on which the window is defined. 
window Specify the window for which you want the widget. 



1 1 .9 Handling Errors 

The X Toolkit Intrinsics let a client register procedures that are to be called whenever a 
fatal or nonfatal error occurs. These facilities are intended for both error reporting and 
logging and for error correction or recovery. 

Two levels of interface are provided: 

• A high-level interface that takes an error name and class and looks the error up in an 
error resource database 

• A low-level interface that takes a simple string 

The high-level functions construct a string to pass to the lower-level interface. The error 
database usually is /usr/lib/Xll/XtErrorDB. 



NOTE 

The application context specific error handling in not implemented 
on many systems. Most implementations will have just one set of 
error handlers. If they are set for different application contexts, the 
one performed last will prevail. 



To obtain the error database (for example, to merge with an application or widget specific 
database), use XtAppGetErrorDat abase. 

XrmDatabase *XtAppGetErrorDatabase (app_context ) 
XtAppContext app ^context ; 

app_context Specifies the application context. 

The XtAppGetErrorDatabase function returns the address of the error database. 
The X Toolkit Intrinsics do a lazy binding of the error database and do not merge in the 
database file until the first call to XtAppGetErrorDatbaseText. 

For a complete listing of all errors and warnings that can be generated by the X Toolkit 
Intrinsics , see Appendix D. 
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The high-level error and warning handler procedure pointers are of the type 
XtErrorMsgHandler: 

typedef void (*XtErrorMsgHandler ) (String, String, String, String, String *, Cardinal *); 
String name; 
String type; 
String class; 
String defaultp; 
String *params; 
Cardinal *num _params; 



name Specifies the name that is concatenated with the specified type to form the 

resource name of the error message. 

type Specifies the type that is concatenated with the name to form the resource 

name of the error message. 

class Specifies the resource class of the error message. 

defaultp Specifies the default message to use if no error database entry is found. 

params Specifies a pointer to a list of values to be substituted in the message. 



num jjarams Specifies the number of values in the parameter list. 

The specified name can be a general kind of error, like invalidParameters or 
invalidWindow, and the specified type gives extra information. Standard printf 
notation is used to substitute the parameters into the message. 

An error message handler can obtain the error database text for an error or a warning by 
calling XtAppGetErrorDatabaseText. 

void XtAppGetErrorDatabaseText(ap/>_c0/rtett, name, type, class, default, buffer return, nbytes , database) 
XtAppContext app_context; 
char *name, *type , *class; 
char * default; 
char *bufferjeturn; 
int nbytes; 

XrmDat abase database; 

app_context Specifies the application context. 

name 

type Specifies the name and type that are concatenated to form the resource 

name of the error message. 

class Specifies the resource class of the error message. 
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default Specifies the default message to use if an error database entry is not 

found. 

buffer jeturn Specifies the buffer into which the error message is to be returned. 
nbytes Specifies the size of the buffer in bytes. 

database Specifies the name of the alternative database that is to be used or 

NULL if the application's database is to be used. 

The XtAppGetErrorDatabaseText returns the appropriate message from the error 
database or returns the specified default message if one is not found in the error database. 

To register a procedure to be called on fatal error conditions, use 
XtAppSetErrorMsgHandler. 

void XtAppSetErrorMsgHandler (app_context , msgjtandler) 
XtAppContext app_context; 
XtErrorMsgHandler msgjtandler; 

app_context Specifies the application context. 

msgjtandler Specifies the new fatal error procedure, which should not return. 

The default error handler provided by the X Toolkit Intrinsics constructs a string from the 
error resource database and calls XtError. Fatal error message handlers should not 
return. If one does, subsequent X Toolkit behavior is undefined. 

To call the high-level error handler, use XtAppErrorMsg. 

void XtAppErrorMsg (,app_context , name, type, class, default, params , num _params) 
XtAppContext app_context; 
String name; 
String type; 
String class; 
String default; 
String *params; 
Cardinal *num jparams; 



app_context Specifies the application context. 
name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

class Specifies the resource class. 

default Specifies the default message to use if an error database entry is not 

found. 
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params Specifies a pointer to a list of values to be stored in the message. 

num _params Specifies the number of values in the parameter list. 

The X Toolkit Intrinsics internal errors all have class XtToolkitError. 

To register a procedure to be called on nonfatal error conditions, use 
X t App S e tWar ningMs gHandl e r . 

void XtAppSetWarningMsgHandler (.app_context, msgjtandler) 
XtAppContext app_context; 
XtErrorMsgHandler msgjtandler; 

app_context Specifies the application context. 

msgjtandler Specifies the new nonfatal error procedure, which usually returns. 

The default warning handler provided by the X Toolkit Intrinsics constructs a string from 
the error resource database and calls XtWarning. 

To call the installed high-level warning handler, use XtAppWarningMsg. 

void XtAppWarningMsg (app_context , name, type, class, default, params , num jtarams) 
XtAppContext app_context; 
String name; 
String type; 
String class; 
String default; 
String *params; 
Cardinal *num _params; 



app_context Specifies the application context. 

name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

class Specifies the resource class. 

default Specifies the default message to use if an error database entry is not 
found. 

params Specifies a pointer to a list of values to be stored in the message. 

num j>arams Specifies the number of values in the parameter list. 



The X Toolkit Intrinsics internal warninings all have class XtToolkitError. 
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The low-level error and warning handler procedure pointers are of type 
XtErrorHandler: 

typedef void (*XtErrorHandler) (String) ; 
String message; 

message Specifies the error message. 

The error handler should display the message string in some appropriate fashion. 

To register a procedure to be called on fatal error conditions, use 
XtAppSetErrorHandler. 

void XtAppSetErrorHandler (.app_context , handler) 
XtAppContext app_context; 
XtErrorHandler handler; 

app_context Specifies the application context. 

handler Specifies the new fatal error procedure, which should not return. 

The default error handler provided by the X Toolkit Intrinsics is _XtError. It prints 
the message to standard error and terminates the application. Fatal error message 
handlers should not return. If one does, subsequent X Toolkit behavior is undefined. 

To call the installed fatal error procedure, use XtAppError. 

void XtAppError {app ^context , message) 
XtAppContext app_context; 
String message; 

app_context Specifies the application context. 

message Specifies the message that is to be reported. 

Most programs should use XtAppErrorMsg, not XtAppError, to provide for 
customization and internationalization of error messages. 

To register a procedure to be called on nonfatal error conditions, use 
X t App S e tWar n ingHandl e r . 

void XtAppSetWarningHandler(fl£>p_C0/tfetf , handler) 
XtAppContext app_context; 
XtErrorHandler handler; 

app_context Specifies the application context. 
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handler Specifies the new nonfatal error procedure, which usually returns. 

The default warning handler provided by the X Toolkit Intrinsics is _XtWarning. It 
prints the message to standard error and returns to the caller. 

To call the installed nonfatal error procedure, use XtAppWarning. 

void XtAppWarning (.app_context , message) 
XtAppContext app_context; 
String message; 

app_context Specifies the application context. 

message Specifies the nonfatal error message that is to be reported. 

Most programs should use XtAppWarningMsg, not XtAppWarning, to provide for 
customization and internationalization of warning messages. 
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Resource File Format 



A 



A resource file contains text representing the default resource values for an application or 
set of applications. The resource file is an ASCII text file that consists of a number of 
lines with the following EBNF syntax: 



resourcefile = {line "\\n"}. 

line = (comment | production). 

comment = T string. 

production = resourcename ":" string. 

resourcename = ["*"] name {("." | "*") name}. 

string = { < any character not including eol > } . 

name = {"A"-"Z" | "a"-"z" | "0"-"9"}. 



If the last character on a line is a backslash (\), that line is assumed to continue on the next 
line. 

To include a newline character in a string, use "\n". 
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Translation Table Syntax B 



B.1 Notation 

Syntax is specified in EBNF notation with the following conventions: 

[ a ] Means either nothing or "a" 

{ a } Means zero or more occurrences of "a" 

All terminals are enclosed in double quotation masks (" "). Informal descriptions are 
enclosed in angle brackets (< >). 

B.2 Syntax 

The syntax of the translation table file is: 
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translationTable = [ directive ] { production } 

directive = ( "#replace" | "#override" | "#augment" ) "\\n" 

production = lhs ":" rhs "\\n" 

lhs = ( event | keyseq ) { "," (event | keyseq) } 

keyseq = """ keychar {keychar} """ 

keychar = [ *'~" | "$" | "\\" ] <ISO Latin 1 character > 

event = [modifierjist] " < "event Jype" > " [ "(" count[" + "] ")" ] {detail} 

modifierjist = ( ["!" | ":"] {modifier} ) | "None" 

modifier = ["""] modifier_name 

count = ("1" | "2" | "3" | "4" | ...) 

modifier_name = "@" <keysym> | < see ModifierNames table below > 

event_type = < see Event Types table below > 

detail = < event specific details > 

rhs = { name "(" [params] ")" } 

name = namechar { namechar } 

namechar = { "a"-"z" | "A"-"Z" | "0"-"9" | "$" | "_" } 

params = string {"," string}. 

string = quoted_string | unquoted_string 

quoted_string = """ {< Latin 1 character > } """ 

unquoted_string = { < Latin 1 character except space, tab, newline, ")" > } 



It is often convenient to include newlines in a translation table to make it more readable. 
In C, indicate a newline with a "\n": 

"<BtnlDown>: DoSomething ( )\n\ 
<Btn2Down> : DoSomethingEls e ( ) " 



B.3 Modifier Names 

The modifier field is used to specify normal X keyboard and button modifier mask bits. 
Modifiers are legal on event types KeyPress, KeyRelease, ButtonPress, 
ButtonRelease, MotionNotify, EnterNotify, Le aveNot if y, and their 
abbreviations. An error is generated when a translation table that contains modifiers for 
any other events is parsed. 

• If the modifierjist has no entries and is not "None", it means "don't care" on all 
modifiers. 

• If an exclamation point (!) is specified at the beginning of the modifier list, it means 
that the listed modifiers must be in the correct state and no other modifiers can be 
asserted. 



B - 2 Translation Table Syntax 



• If any modifiers are specified and an exclamation point (!) is not specified, it means 
that the listed modifiers must be in the correct state and "don't care" about any 
other modifiers. 

• If a modifier is preceded by a tilde (~), it means that that modifier must not be 
asserted. 

• If "None" is specified, it means no modifiers can be asserted. 

• If a colon (:) is specified at the beginning of the modifier list, it directs the X Toolkit 
Intrinsics to apply any standard modifiers in the event to map the event keycode into 
a keysym. The default standard modifiers are Shift and Lock, with the interpretation 
as defined in X Window System Protocol, X Version 11. The resulting keysym must 
exactly match the specified keysym, and the nonstandard modifiers in the event must 
match the modifier_list. For example, ":<Key>a" is distinct from ":<Key>A", and 
":Shift<Key>A" is distinct from ":<Key>A". 

• If a colon (:) is not specified, no standard modifiers are applied. Then, for example, 
"<Key>A" and "<Key>a" are equivalent. 

In key sequences, a circumflex (~) is an abbreviation for the Control modifier, a dollar sign 
($) is an abbreviation for Meta, and a backslash (\) can be used to quote any character, in 
particular a double quote ("), a circumflex (^), a dollar sign ($), and another backslash (\). 
Briefly: 

No Modifiers: None <event> detail 

Any Modifiers : <event> detail 

Only these Modifiers: ! modi mod2 <event> detail 

These modifiers and any others :modl mod2 <event> detail 

The use of "None" for a modifier_list is identical to the use of and exclamation point with 
no modifers. 
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Modifier 


Abbreviation 


Meaning 


Ctrl 


c 


Control modifier bit 


Shift 


s 


Shift modifier bit 


Lock 


1 


Lock modifier bit 


Meta 


m 


Meta key modifier (see below) 


Hyper 


h 


Hyper key modifier (see below) 


Super 


su 


Super key modifier (see below) 


Alt 


a 


Alt key modifier (see below) 


Modi 




Modi modifier bit 


Mod2 




Mod2 modifier bit 


Mod3 




Mod3 modifier bit 


Mod4 




Mod4 modifier bit 


Mod5 




Mod5 modifier bit 


Buttonl 




Buttonl modifier bit 


Button2 




Button2 modifier bit 


Button'? 




Tlnffnn'? mr»Hiripr nit 


Button4 




Button4 modifier bit 


Button5 




Button5 modifier bit 


ANY 




Any combination 



A key modifier is any modifier bit whose corresponding keycode contains the 
corresponding left or right keysym. For example, "m" or "Meta" means any modifier bit 
mapping to a keycode whose keysym list contains XK_Meta_L or XK_Meta_R. Note that 
this interpretation is for each display, not global or even for each application context. The 
Control, Shift, and Lock modifier names refer explicitly to the corresponding modifier bits; 
there is no additional interpretation of keysyms for these modifiers. 

Because it is possible to associate arbitrary keysyms with modifiers, the set of modifier key 
modifiers is extensible. The"@" < keysym > syntax means any modifier bit whose 
corresponding keycode contains the specified keysym. 

A modifierjist/keysym combination in a translation matches a modifiers/keycode 
combination in an event in the following: 

1. If a colon (:) is used, the X Toolkit Intrinsics call the display's XtKeyProc with 
the keycode and modifiers. To match, (modifiers & ~modifiers_return) must equal 
modifier_list, and keysym_return must equal the given keysym. 
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2. If (:) is not used, the X Toolkit Intrinsics mask off all don't-care bits from the 
modifiers. This value must be equal to modifier_list. Then, for each possible 
combination of don't-care modifiers in the modif ierjist, the X Toolkit Intrinsics call 
the display's XtKeyProc with the keycode and that combination ORed with the 
cared-about modifier bits from the event. Keysym_return must match the keysym in 
the translation. 



B.4 Event Types 

The EventType field describes XEvent types. The following are the currently defined 
EventType values: 
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Type 


Meaning 


Key 


KeyPress 


KeyDown 




KeyUp 


KeyRelease 


BtnDown 


ButtonPress 


BtnUp 


ButtonRelea.se 


Motion 


MotionNotify 


PtrMoved 


MouseMoved 




Enter 


EnterNo tif y 


Enfer^Vindow 




Leave 


LeaveNotif y 


LeaveWindow 




Focusln 


Focusln 


FocusOut 


FocusOut 


Keymap 


KeymapNo t i f y 


Expose 


Expose 


GrExp 


Graphics Expose 


NoExp 


NoExpose 


Visible 


VisibilityNotify 


Create 


CreateNotify 


Destroy 


DestroyNotify 


Unmap 


UnmapNotif y 


Map 


MapNotify 


MapReq 


MapRe que s t 


Reparent 


ReparentNotify 


Configure 


Conf igureNotify 


ConfigureReq 


C onf i gur eRe que s t 


Grav 


GravityNotify 


ResReq 


ResizeRequest 


Circ 


CirculateNotify 


CircReq 


CirculateRequest 


Prop 


Proper tyNot if y 


SelClr 


Select ionClear 


SelReq 


SelectionRequest 


Select 


Select ionNotify 


Clrmap 


ColormapNotify 


Message 


ClientMessage 


Mapping 


MappingNotify 
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The supported abbreviations are: 



Abbreviation 


Meaning 


Ctrl 


KeyPress with control modifier 


Meta 


KeyPress with meta modifier 


Shift 


KeyPress with shift modifier 


BtnlDown 


ButtonPress with Btnl detail 


BtnlUp 


ButtonRelease with Btnl detail 


Btn2Down 


ButtonPress with Btn2 detail 


Btn2Up 


ButtonRelease with Btn2 detail 


Btn3Down 


ButtonPress with Btn3 detail 


Btn3Up 


ButtonRelease with Btn3 detail 


Btn4Down 


ButtonPress with Btn4 detail 


Btn4Up 


ButtonRelease with Btn4 detail 


Btn5Down 


ButtonPress with Btn5 detail 


Btn5Up 


ButtonRelease with Btn5 detail 


BtnMotion 


MotionNotif y with any button modifier 


BtnlMotion 


MotionNotify with Buttonl modifier 


Btn2Motion 


MotionNotify with Button2 modifier 


Btn3Motion 


MotionNotify with Button3 modifier 


Btn4Motion 


MotionNotify with Button4 modifier 


Btn5Motion 


MotionNotify with Button5 modifier 



The Detail field is event specific and normally corresponds to the detail field of an X 
Event, for example, <Key>A. If no detail field is specified, then ANY is assumed. 

A keysym can be specified as any of the standard keysym names, a hexadecimal number 
prefixed with "Ox" or "OX", an octal number prefixed with "0" or a decimal number. A 
keysym expressed as a single digit is interpreted as the corresponding Latin 1 keysym, for 
example, "0" is the keysym XK_0. Other single character keysyms are treated as literal 
constants from Latin 1, for example, "!" is treated as 0x21. 

Standard keysym names are as defined in < Xll/keysymdef . h > with the "XK_" prefix 
removed. For example, "!" is XK_exclam" with a value of 0x021. To reference the "!" 
keysym, use "exclam." 
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B.5 Canonical Representation 



Every translation table has a unique, canonical text representation. This representation is 
passed to a widget's display_accelerator method to describe the accelerators 
installed on that widget. The canonical representation of a translation table file is (see also 
"Syntax"): 



translationTable 


= 


{ production } 


production 




lhs ":" rhs "\\n" 


lhs 




event { "," event } 


event 


— 


[modifierjist] "<"event_type">" [ "(" count[" + "] ")" ] {detail} 


modifier list 




["!" | ":"] {modifier} 


modifier 




['""] modifier name 


count 




("1" | "2" | "3" | "4" | ...) 


modifier name 




"@" <keysym> | < see canonical modifier names below > 


event_type 




<see canonical event types below > 


detail 




< event specific details > 


rhs 




{ name "(" [params] ")" } 


name 




namechar { namechar } 


namechar 




{ "a M -"z" | "A"-"Z" | "0"-"9" | "$" | "_" } 


params 




string {"," string}. 


string 




quoted string 


quoted_string 




{< Latin 1 character >} 



The canonical modifier names are: 



Ctrl Buttonl 
Shift Button2 
Lock Button3 
Modi Button* 
Mod2 Button5 
Mod3 
Mod4 
Mod5 



The canonical event types are: 
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Key Press 

ButtonPress 

MotionNotify 

LeaveNotify 

FocusOut 

Expose 

NoExpose 

CreateNotify 

UnmapNotify 

MapRequest 

Conf igureNotify 

GravityNotify 

CirculateNotify 

PropertyNotify 

Select ionRequest 

ColormapNotify 



KeyRelease 

ButtonRelease 

EnterNotify 

Focus In 

KeymapNotify 

GraphicsExpose , 

VisibilityNotify 

DestroyNotify 

MapNotify 

ReparentNotify 

C onf i gur eRe que s t 

ResizeRequest 

CirculateRequest 

Select ionClear 

Select ionNot if y 

ClientMessage 



B.6 Examples 

• Always put more specific events in the table before more general ones: 

Shift <BtnlDown> : twas()\n\ 
<BtnlDown> : brilligO 

• For double-click on Button 1 Up with Shift, use this specification: 

Shift<BtnlUp>(2) : and() 

This is equivalent to the following line with appropriate timers set between events: 

Shift<BtnlDown>,Shift<BtnlUp>,Shift<BbnlDovm>,Shift<BtnlUp> : and( ) 

• For double-click on Button 1 Down with Shift, use this specification: 

Shift<BtnlDown>(2) : the() 

This is equivalent to the following line with appropriate timers set between events: 
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Shift<BtnlDown>,Shift<BtnlUp>,Shift<BtnlDovm> : the() 



• Mouse motion is always discarded when it occurs between events in a table where no 
motion event is specified: 

<BtnlDown>,<BtnlUp> : slithyO 

This is taken, even if the pointer moves a bit between the down and up events. 
Similarly, any motion event specified in a translation matches any number of motion 
events. If the motion event causes an action procedure to be invoked, the procedure 
is invoked after each motion event. 

• If an event sequence consists of a sequence of events that is also a non-initial 
subsequence of another translation, it is not taken if it occurs in the context of the 
longer sequence. This occurs mostly in sequences like the following: 

<BtnlDown>,<BtnlUp> : toves()\n\ 
<BtnlUp> : did() 

The second translation is taken only if the button release is not preceded by a button 
press or if there are intervening events between the press and the release. Be 
particularly aware of this when using the repeat notation, above, with buttons and 
keys because their expansion includes additional events, and when specifying motion 
events because they are implicitly included between any two other events. In 
particular, pointer motion and double-click translations cannot coexist in the same 
translation table. 

• For single click on Button 1 Up with Shift and Meta, use this specification: 

Shift Meta <BtnlDown>, Shift Meta<BtnlUp>: gyre() 

• You can use a plus sign (+) to indicate "for any number of clicks greater than or 
equal to count"; for example: 

Shift <BtnlUp>(2+) : and() 

• To indicate EnterNotify with any modifiers, use this specification: 

<Enter> : gimble() 

• To indicate EnterNotify with no modifiers, use this specification: 
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None <Enter> : in() 

• To indicate EnterNotify with Button 1 Down and Button 2 Up and don't care 
about the other modifiers, use this specification: 

Buttonl ~Button2 <Enter> : the() 

• To indicate EnterNotify with Buttonl Down and Button2 Down exclusively, use 
this specification: 

! Buttonl Button2 <Enter> : wabe() 

You do not need to use a tilde (") with an exclamation point (!). 
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Conversion Notes 



c 



In the X Version 10 and alpha release X Version 11 X Toolkit each widget class 
implemented an Xt< Widget > Create (for example, XtLabelCreate) function, in which 
most of the code was identical from widget to widget. In this X Toolkit, a single generic 
XtCreateWidget performs most of the common work and then calls the initialize 
procedure implemented for the particular widget class. 

Each composite widget class also implemented the procedures Xt< Widget >Add and an 
Xt< Widget > Delete (for example, XtButtonBoxAddButton and 
XtButtonBoxDeleteButton). In the beta release X Version 11 X Toolkit, the 
composite generic procedures XtManageChildren and XtUnmanage Children 
perform error-checking and screening out of certain children. Then, they call the 
change_managed procedure implemented for the widget's composite class. If the widget's 
parent has not yet been realized, the call on the change_managed procedure is delayed 
until realization time. 

Old style calls can be implemented in the X Toolkit by defining one-line procedures or 
macros that invoke a generic routine. For example, you could define the macro 
XtCreateLabel as: 



#define XtCreateLabel(«ome, parent, orgs, numjtrgs) \ 

((LabelWidget) XtCreateWidget {name, labelWidgetClass , parent, orgs, num_args)) 



Pop-up shells no longer automatically perform an XtManageChild on their child within 
their insert_child procedure. Creators of pop-up children need to call XtManageChild 
themselves. 

As a convenience to people converting from earlier versions of the toolkit and for greater 
orthogonality, the following routines exist: Xtlnitialize, XtMainLoop, 
XtNextEvent, XtProcessEvent, XtPeekEvent, XtPending, XtAddlnput, 
XtAddTimeOut, XtAddWorkProc, and XtCreateApplicationShell. 
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Widget Xtlnitialize (s/te//_«a/ne, application _class , options, num options, argc, argy) 
String shell jiame; 
String application jdass ; 
XrmOptionDescRec optionsl]; 
Cardinal num_options; 
Cardinal *argc; 
String arg>>[ ] ; 



shell jiame This parameter is ignored; therefore, you can specify NULL 



application jlass 
options 



num_options 

argc 

argv 



Specifies the class name of this application. 

Specifies how to parse the command line for any application- 
specific resources. The options argument is passed as a parameter 
to XrmParseCommand. For further information, see 
Programming with Xlib . 

Specifies the number of entries in options list. 

Specifies a pointer to the number of command line parameters. 

Specifies the command line parameters. 



Xtlnitialize calls XtToolkitlnitialize to initialize the toolkit internals, 
creates a default application context for use by the other convenience routines, then calls 
XtOpenDisplay with a displayjstring of NULL and an application_name of NULL, and 
finally calls XtAppCreateShell with an application_name of NULL and returns the 
created shell. The semantics of calling Xtlnitialize more than once are undefined. 
See XtCreateApplicationContext, XtDisplaylnitialize, and 
XtAppCreateShell for more information. 



void XtMainLoopO 

XtMainLoop first reads the next incoming file, timer, or X event by calling 
XtNextEvent. Then, it dispatches this to the appropriate registered procedure by 
calling XtDispatchEvent. This can be used as the main loop of X Toolkit 
applications, and, as such, it does not return. Applications are expected to exit in response 
to some user action. This routine has been replaced by XtAppMainLoop. 

There is nothing special about XtMainLoop. It is simply an infinite loop that calls 
XtNextEvent then XtDispatchEvent. 



void XtNextEvent {event jeturn) 
XEvent *event jeturn ; 



event jeturn Returns the event information to the specified event structure. 
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If no input is on the X input queue for the default application context, XtNextEvent 
flushes the X output buffer and waits for an event while looking at the other input sources 
and timeout values and calling any callback procedures triggered by them. This routine 
has been replaced by XtAppNextEvent. Xtlnitialize must be called before 
using this routine. 

void XtProcessEvent(masfc) 
XtlnputMask mask; 

mask Specifies the type of input to process. 

XtProcess Event processes one input event, timeout, or alternate input source 
(depending on the value of mask), waiting if necessary. It has been replaced by 
XtAppProcessEvent. Xtlnitialize must be called before using this function. 

Boolean XtPeekEvent (event return) 
XEvent *eventjeturn; 

event jetum Returns the event information to the specified event structure. 

If there is an event in the queue for the default application context, XtPeekEvent fills 
in the event and returns a non-zero value. If no X input is on the queue, XtPeekEvent 
flushes the output buffer and blocks until input is available, possibly calling some timeout 
callbacks in the process. If the input is an event, XtPeekEvent fills in the event and 
returns a non-zero value. Otherwise, the input is for an alternate input source, and 
XtPeekEvent returns zero. This routine has been replaced by XtAppPeekEvent. 
Xtlnitialize must be called before using this routine. 

Boolean XtPendingO 

The XtPending returns a nonzero value if there are events pending from the X server 
or other input sources in the default application context. If there are no events pending, it 
flushes the output buffer and returns a zero value. It has been replaced by 
XtAppPending. Xtlnitialize must be called before using this routine. 

Xtlnputld XtAddlnput (source , condition, proc, client data) 
int source; 
caddr_t condition; 
XtlnputCallbackProc proc; 
caddr_t client Jiata; 
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source 



Specifies the source file descriptor on an operating system dependent 
device specification. 



condition Specifies the mask that indicates either a read, write, or exception 

condition or some operating system dependent condition. 

proc Specifies the procedure that is called when input is available. 

client jiata Specifies the parameter to be passed to proc when input is available. 

The XtAddlnput function registers with the X Toolkit default application context a new 
source of events, which is usually file input but can also be file output. (The word "file" 
should be loosely interpreted to mean any sink or source of data.) XtAddlnput also 
specifies the conditions under which the source can generate events. When input is 
pending on this source in the default application context, the callback procedure is called. 
This routine has been replaced by XtAppAddlnput. Xtlnitialize must be called 
before using this routine. 

Xtlntervalld XtAddTimeOut(w«e/va/, proc, client _data) 
unsigned long interval; 
XtTimerCallbackProc proc; 
caddr_t client _data; 

interval Specifies the time interval in milliseconds. 

proc Specifies the procedure to be called when time expires. 

client _data Specifies the parameter to be passed to proc when it is called. 

The XtAddTimeOut function creates a timeout in the default application context and 
returns an identifier for it. The timeout value is set to interval. The callback procedure 
will be called after the time interval elapses, after which the timeout is removed. This 
routine has been replaced by XtAppAddTimeOut. Xtlnitialize must be called 
before using this routine. 

XtWorkProcId XtAddWorkProc {proc, closure) 
XtWorkProc proc; 
Opaque closure; 

proc Procedure to call to do the work. 

closure Client data to pass to proc when it is called. 

This routine registers a work proc in the default application context. It has been replaced 
by XtAppAddWorkProc. Xtlnitialize must be called before using this routine. 
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Widget XtCreateApplicationShell(«ame, widget jlass , orgs, numjags) 
String name; 
WidgetClass widget _class ; 
ArgList orgs; 
Cardinal numjags; 



name This parameter is ignored; therefore, you can specify NULL. 

widget_class Specifies the widget class pointer for the created application shell 

widget. This will usually be topLevelShellWidgetClass or a 
subclass thereof. 

args Specifies the argument list to override the resource defaults. 

num _args Specifies the number of arguments in args. 

XtCreateApplicationShell calls XtAppCreateShell with an application_name 
of NULL, the application_class passed to Xtlnitialize and the default application 
context created by Xtlnitialize . This routine has been replaced by 
XtAppCreateShell. 



To register a new converter, use the procedure XtAddConverter. 

void XtAddConverter (fivmjype, tojype, converter, convert _args , num_args) 
String ffomjype; 
String tojype; 
XtConverter converter; 
XtConvertArgList convert jags ; 
Cardinal num jags ; 



fromjype Specifies the source type. 

tojype Specifies the destination type. 

converter Specifies the type converter procedure. 

convert jirgs Specifies how to compute the additional arguments to the converter or 
NULL. 

num_args Specifies the number of additional arguments to the converter or zero. 

For the few type converters that need additional arguments, the X Toolkit Intrinsics 
conversion mechanism provides a method of specifying how these arguments should be 
computed. The enumerated type XtAddressMode and the structure 
XtConvertArgR.ee specify how each argument is derived. These are defined in 
<Xll/Convert .h>. 



typedef enum { 
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/* address mode parameter representation */ 

XtAddress, /* address */ 

XtBaseOffset, /* offset */ 

Xtlmmediate, /* constant */ 

XtResourceString, /* resource name string */ 

XtResourceQuark /* resource name quark */ 
} XtAddressMode; 

typedef struct { 

XtAddressMode address_mode ; 

caddr_t address_id; 

Cardinal size; 
} XtConvertArgRec, *XtConvertArgList; 

The address_mode field specifies how the address_id field should be interpreted. 
XtAddress causes address_id to be interpreted as the address of the data. 
XtBaseOffset causes address_id to be interpreted as the offset from the widget base. 
Xtlmmediate causes address_id to be interpreted as a constant. 
XtResourceString causes address_id to be interpreted as the name of a resource that 
is to be converted into an offset from widget base. XtResourceQuark is an internal 
compiled form of an XtResourceString. The size field specifies the length of the 
data in bytes. 

The following provides the code that was used to register the CvtStringToPixel routine 
shown earlier: 

static XtConvertArgRec colorConvertArgs [ ] = { 

{XtBaseOffset, (caddr_t) XtOff set (Widget, core. screen) , sizeof (Screen *)}, 
{XtBaseOffset, (caddr_t) XtOff set (Widget, core. colormap) , sizeof (Colormap) } 

}; 

XtAddConverter(XtRString, XtRPixel, CvtStringToPixel, 
colorConvertArgs, XtNumber ( colorConvertArgs ) ) ; 

The conversion argument descriptors colorConvertArgs and screenConvertArg are 
predefined. The screenConvertArg descriptor puts the widget's screen field into args[0]. 
The colorConvertArgs descriptor puts the widget's screen field into args[0], and the 
widget's colormap field into args[l]. 

Conversion routines should not just put a descriptor for the address of the base of the 
widget into args[0], and use that in the routine. They should pass in the actual values that 
the conversion depends on. By keeping the dependencies of the conversion procedure 
specific, it is more likely that subsequent conversions will find what they need in the 
conversion cache. This way the cache is smaller and has fewer and more widely applicable 
entries. 

To deallocate a shared GC when it is no longer needed, use XtDestroyGC. 
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void XtDestroyGC(H\ gc) 
Widget w; 
GC gc; 

w Specifies the widget. 

gc Specifies the GC to be deallocated. 

References to sharable GCs are counted and a free request is generated to the server 
when the last user of a given GC destroys it. Note that some earlier versions of 
XtDestroyGC had only a gc argument. Therefore, this function is not very portable, and 
you are encouraged to use XtReleaseGC instead. 

To declare an action table and register it with the translation manager, use 
XtAddActions. 

void XtAddActions (actions, num_actions) 
XtActionList actions; 
Cardinal numjictions; 

actions Specifies the action table to register. 

num_args Specifies the number of entries in this action table. 

If more than one action is registered with the same name, the most recently registered 
action is used. If duplicate actions exist in an action table, the first is used. The X Toolkit 
Intrinsics register an action table for MenuPopup and MenuPopdown as part of X 
Toolkit initialization. 

To set the X Toolkit Intrinsics selection timeout, use XtSetSelectionTimeout. 

void XtSetSelectionTimeout (timeout) 
unsigned long timeout; 

timeout Specifies the selection timeout in milliseconds. 

To get the current selection timeout value, use XtGetSelectionTimeout. 

unsigned long XtGetSelectionTimeout ( ) 
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The selection timeout is the time within which the two communicating applications must 
respond to one another. If one of them does not respond within this interval, the X Toolkit 
Intrinsics aborts the selection request. The default value of the selection timeout is five 
seconds. 

To obtain the error database (for example, to merge with an application or widget specific 
database), use XtGetErrorDatabase. 

XrmDatabase *XtGetErrorDatabase( ) 

The XtGetErrorDatabase function returns tha address of the error database. The X 
Toolkit Intrinsics do a lazy binding of the error database and do not merge in the database 
file until the first call to XtGetErrorDatbaseText. 

For a complete listing of all errors and warnings that can be generated by the X Toolkit 
Intrinsics , see Appendix D. 

An error message handler can obtain the error database text for an error or a warning by 
calling XtGetErrorDatabaseText. 

void XtGetErrorDatabaseText {name, type, class, default, buffer jetum, nbytes) 
char *name, *type, *class; 
char ^default; 
char *bujfer_return ; 
int nbytes; 

name 

type Specifies the name and type that are concatenated to form the resource 

name of the error message. 

class Specifies the resource class of the error message. 

default Specifies the default message to use if an error database entry is not 

found. 

buffer jeturn Specifies the buffer into which the error message is to be returned. 
nbytes Specifies the size of the buffer in bytes. 

The XtGetErrorDatabaseText returns the appropriate message from the error 
database or returns the specified default message if one is not found in the error database. 

To register a procedure to be called on fatal error conditions, use 
Xt S e tEr r orMs gHandler . 
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void XtSetErrorMsgHandler (msgjiandler) 
XtErrorMsgHandler msgjiandler; 



msgjiandler Specifies the new fatal error procedure, which should not return. 

The default error handler provided by the X Toolkit Intrinsics constructs a string from the 
error resource database and calls XtError . Fatal error message handlers should not 
return. If one does, subsequent X Toolkit behavior is undefined. 

To call the high-level error handler, use XtErrorMsg. 

void XtErrorMsg {name, type, class, default, params, num _params) 
String name', 
String type; 
String class; 
String default; 
String *params; 
Cardinal *num _params; 



name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

class Specifies the resource class. 

default Specifies the default message to use if an error database entry is not found. 

params Specifies a pointer to a list of values to be stored in the message. 



num jfarams Specifies the number of values in the parameter list. 

The X Toolkit Intrinsics internal errors all have class XtToolkitError. 

To register a procedure to be called on nonfatal error conditions, use 
XtSetWamingMsgHandler. 

void XtSetWamingMsgHandler (msgjiandler) 
XtErrorMsgHandler msgjiandler; 

msgjiandler Specifies the new nonfatal error procedure, which usually returns. 

The default warning handler provided by the X Toolkit Intrinsics constructs a string from 
the error resource database and calls XtWarning. 

To call the installed high-level warning handler, use XtWarningMsg. 
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void XtWarningMsg(«a/we, type, class, default, params , num _params) 
String name; 
String type; 
String class; 
String default; 
String *params; 
Cardinal *num _params; 



name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

class Specifies the resource class. 

default Specifies the default message to use if an error database entry is not found. 

params Specifies a pointer to a list of values to be stored in the message. 



num _params Specifies the number of values in the parameter list. 

The X Toolkit Intrinsics internal warninings all have class XtToolkitError . 

To register a procedure to be called on fatal error conditions, use 
XtSetErrorHandler. 

void XtSetErrorHandler (.handler) 
XtErrorHandler handler; 

handler Specifies the new fatal error procedure, which should not return. 

The default error handler provided by the X Toolkit Intrinsics is _XtError. It prints 
the message to standard error and terminates the application. Fatal error message 
handlers should not return. If one does, subsequent X Toolkit behavior is undefined. 

To call the installed fatal error procedure, use XtError. 

void XtError (message ) 
String message; 

message Specifies the message that is to be reported. 

Most programs should use XtErrorMsg, not XtError, to provide for customization 
and internationalization of error messages. 

To register a procedure to be called on nonfatal error conditions, use 
XtSetWamingHandler. 
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void XtSetWarningHandler(#a/J<//er) 
XtErrorHandler handler; 

handler Specifies the new nonfatal error procedure, which usually returns. 

The default warning handler provided by the X Toolkit Intrinsics is _XtWarning. It 
prints the message to standard error and returns to the caller. 

To call the installed nonfatal error procedure, use XtWarning. 

void XtWarning {message) 
String message; 

message Specifies the nonfatal error message that is to be reported. 

Most programs should use XtWarningMsg, not XtWarning, to provide for 
customization and internationalization of warning messages. 
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Standard Errors and Warnings 



D 



All X Toolkit errors and warnings have class XtToolkitError . The following two 
tables summarize all of the errors and warnings that can be generated by the X Toolkit. 



Errors 



Name 


Type 


Default Message 


allocError 


calloc 


Cannot perform calloc 


allocError 


malloc 


Cannot perform malloc 


allocError 


realloc 


Cannot perform realloc 


communicationError 


select 


Select failed 


internalError 


shell 


Shell's window manager interaction 






is broken 


invalidArgCount 


xtGetValues 


Argument count > 0 on NULL 






argument list in XtGetValues 


invalidArgCount 


xtSetValues 


Argument count > 0 on NULL 






argument list in XtSetValues 


invalidClass 


constraintSet Value 


Subclass of Constraint required in 






CallConstraintSetValues 


invalidClass 


xtAppCreateShell 


XtAppCreateShell requires non- 






NULL widget class 


invalidClass 


xtCreatePopupShell 


XtCreatePopupShell requires non- 






NULL widget class 


invalidClass 


xtCreateWidget 


XtCreateWidget requires non- 






NULL widget class 


invalidClass 


xtPopdown 


XtPopdown requires a subclass of 






shellWidgetClass 


invalidClass 


xtPopup 


XtPopup requires a subclass of 






shellWidgetClass 


invalidDimension 


xtCreateWindow 


Widget %s has zero width and/or 






height 


invalidDimension 


shellRealize 


Shell widget %s has zero width 



and/or height 
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invalidDisplay xtlnitialize 
invalidGeometryManagerxtMakeGeometryRequest 



invalidParameter 

invalidParameter 

invalidParameters 

invalidParameters 

invalidParent 

invalidParent 

invalidParent 

invalidParent 

invalidParent 

invalidParent 

invalidParent 

invalidPopup 

invalidPopup 

invalidProcedure 

invalidProcedure 

invalidWindow 

missingEvent 

noAppContext 

noPerDisplay 

noPerDisplay 



noSelectionProperties freeSelectionProperty 



nullProc 

subclassMismatch 



Can't Open display 
XtMakeGeometryRequest - parent 
has no geometry manger 
RemovePopupFromParent requires 
non-NULL popuplist 
invalid condition passed to 
XtAddlnput 

MenuPopup wants exactly one 
argument 

XtMenuPopdown called with 
num_params ! = 0 or 1 
Application shell is not a windowed 
widget? 

XtCreatePopupShell requires non- 
NULL parent 

XtCreateWidget requires non- 
NULL parent 

XtMakeGeometryRequest - NULL 
parent. Use Set Values instead 
XtMakeGeometryRequest - parent 
not composite 

Attempt to manage a child when 
parent is not Composite 
Attempt to unmanage a child when 
parent is not Composite 
Can't find popup in _XtMenuPopup 
Can't find popup in _XtMenuPopup 
Unresolved inheritance operation 
No realize class procedure defined 
Event with wrong window 
Events are disappearing from under 
Shell 

widgetToApplicationContext Couldn't find ancestor with display 

information 

Couldn't find per display 
information 

Couldn't find per display 
information 

internal error: no selection property 
context for display 
NULL insert_child procedure 
Widget class %s found when 
subclass of %s expected: %s 



removePopupFromParent 
XtAddlnput 
xtMenuPopupAction 
xtmenuPopdown 



realize 



XtCreatePopupShell 

XtCreateWidget 

XtMakeGeometryRequest 

XtMakeGeometryRequest 

xtManageChildren 

xtUnmanageChildren 



xtMenuPopup 

xtMenuPopup 

inheritanceProc 

realizeProc 

eventHandler 

shell 



closeDisplay 
getPerDisplay 



insertChild 
xtCheckSubclass 
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translationError mergingTablesWithCycles Trying to merge translation tables 

with cycles, and can't resolve this 
cycle. 

wrongParameters cvtlntOrPixelToXColor Pixel to color conversion needs 

screen and colormap arguments 

wrongParameters cvtStringToCursor String to cursor conversion needs 

screen argument 

wrongParameters cvtStringToFont String to font conversion needs 

screen argument 

wrongParameters cvtStringToFontStruct String to cursor conversion needs 

screen argument 

wrongParameters cvtStringToPixel String to pixel conversion needs 

screen and colormap arguments 



Warnings 



Name 



Type 



Default Message 



ambigiousParent 


xtManageChildren 


ambigiousParent 


xtUnmanageChildren 


communicationError 


windowManager 


conversionError 


string 


displayError 


invalidDisplay 


grabError 


grabDestroyCallback 


grabError 


grabDestroyCallback 


grabError 


xtRemoveGrab 


initializationError 


xtlnitialize 


invalidArgCount 


getResources 


invalidCallbackList 


xtAddCallbacks 


invalidCallbackList 


xtCallCallback 


invalidCallbackList 


xtOverrideCallback 



Not all children have same parent 

in XtManageChildren 

Not all children have same parent 

in XtUnmanageChildren 

Window Manager is confused 

Cannot convert string "%s" to type 

"%s" 

Can't find display structure 
XtAddGrab requires exclusive grab 
if springjoaded is TRUE 
XtAddGrab requires exclusive grab 
if spring_loaded is TRUE 
XtRemoveGrab asked to remove a 
widget not on the grab list 
Initializing Resource Lists twice 
argument count > 0 on NULL 
argument list 

Cannot find callback list in 

XtAddCallbacks 

Cannot find callback list in 

XtCallCallbacks 
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invalidCallbackList 

invalidCallbackList 

invalidChild 

invalidChild 

invalidDepth 
invalidGeometry 

invalidParameters 

invalidParameters 

invalidParameters 

invalidParent 

invalidPopup 

invalidPopup 

invalidProcedure 

invalidProcedure 

invalidProcedure 

invalidResourceCount 

invalidResourceName 

invalidShell 
invalidSizeOverride 

invalidTypeOverride 

invalidWidget 



xtRemoveAUCallback 

xtRemoveCallbacks 

xtManageChildren 

xtUnmanageChildren 

setValues 

xtMakeGeometryRequest 

compileAccelerators 

compileTranslations 

mergeTranslations 

xtCopyFromParent 

unsupportedOperation 

unsupportedOperation 

deleteChild 

inputHandler 

set_values_almost 

getResources 

computeArgs 

xtTranslateCoords 
xtDependencies 

xtDependencies 

removePopupFromParent 



Cannot find callback list in 

XtOverrideCallbacks 

Cannot find callback list in 

XtRemoveAUCallbacks 

Cannot find callback list in 

XtRemoveCallbacks 

null child passed to 

XtManageChildren 

Null child passed to 

XtUnmanageChildren 

Can't change widget depth 

Shell subclass did not take care of 

geometry in XtSet Values 

String to AcceleratorTable needs no 

extra arguments 

String to TranslationTable needs no 
extra arguments 
MergeTM to TranslationTable 
needs no extra arguments 
CopyFromParent must have non- 
NULL parent 

Pop-up menu creation is only 

supported on ButtonPress or 

EnterNotify events. 

Pop-up menu creation is only 

supported on ButtonPress or 

EnterNotify events. 

null delete_child procedure in 

XtDestroy 

XtRemovelnput: Input handler not 
found 

set_values_almost procedure 
shouldn't be NULL 
resource count > 0 on NULL 
resource list 

Cannot find resource name %s as 
argument to conversion 
Widget has no shell ancestor 
Representation size %d must match 
superclass's to override %s 
Representation type %s must 
match superclass's to override %s 



D - 4 Standard Errors and Warnings 



noColormap 


cvtStringToPixel 


registerWindowError 


xtRegisterWindow 


registerWindowError 


xtUnregisterWindow 


translation error 


nullTable 


translation error 


nullTable 


translationError 


ambigiousActions 


translationError 


mergingNullTable 


translationError 


nullTable 


translationError 


unboundActions 


translationError 


xtTranslatelnitialize 


translationParseError 


snowline 


translationParseError 


parseError 


translationParseError 


parseS tring 


typeConversionError 


noConverter 


versionMismatch 


widget 


wrongParameters 


cvtlntToBool 


wrongParameters 


cvtlntToBoolean 


wrongParameters 


cvtlntToFont 


wrongParameters 


cvtlntToPixel 


wrongParameters 


cvtlntToPixmap 


wrongParameters 


cvtlntToShort 


wrongParameters 


cvtStringToBool 


wrongParameters 


cvtStringToBoolean 



RemovePopupFromParent, widget 
not on parent list 

Cannot allocate colormap entry for 

"%s" 

Attempt to change already 
registered window. 
Attempt to unregister invalid 
window. 

Can't remove accelerators from 
NULL table 

Tried to remove non-existant 
accelerators 

Overriding earlier translation 

manager actions. 

Old translation table was null, 

cannot modify. 

Can't translate event thorugh 

NULL table 

Actions not found: %s 

Intializing Translation manager 

twice. 

... found while parsing '%s' 
translation table syntax error: %s 
Missing '\\ 

No type converter registered for 
Widget class %s version mismatch: 
widget %d vs. intrinsics %d. 
Integer to Bool conversion needs no 
extra arguments 
Integer to Boolean conversion 
needs no extra arguments 
Integer to Font conversion needs no 
extra arguments 

Integer to Pixel conversion needs 

no extra arguments 

Integer to Pixmap conversion needs 

no extra arguments 

Integer to Short conversion needs 

no extra arguments 

String to Bool conversion needs no 

extra arguments 

String to Boolean conversion needs 
no extra arguments 



Standard Errors and Warnings D - 5 



wrongParameters cvtStringToDisplay String to Display conversion needs 

no extra arguments 

wrongParameters cvtStringToFile String to File conversion needs no 

extra arguments 

wrongParameters cvtStringToInt String to Integer conversion needs 

no extra arguments 

wrongParameters cvtStringToShort String to Integer conversion needs 

no extra arguments 

wrongParameters cvtStringToUnsignedChar String to Integer conversion needs 

no extra arguments 

wrongParameters cvtXColorToPixel Color to Pixel conversion needs no 

extra arguments 



D - 6 Standard Errors and Warnings 



StringDefs.h Header File 



E 



The S tr ingDef s . h header file contains: 



/* Resource names */ 




#define 


XtNaccelerators 


"accelerators" 


#define 


XtNallowHoriz 


"allowHoriz" 


#define 


XtNallowVert 


"allowVert" 


#define 


XtNancestorSensitive 


"ancestorSensitive" 


#define 


XtNbackground 


"background" 


#define 


XtNbackgroundPixmap 


"backgroundPixmap" 


#def ine 


XtNborderColor 


"borderColor" 


#define 


XtNborder 


"borderColor" 


#define 


XtNborderPixmap 


"borderPixmap" 


#define 


XtNborderWidth 


"borderWidth" 


#define 


XtNcallback 


"callback" 


#define 


XtNcolormap 


"colormap" 


#def ine 


XtNdepth 


"depth" 


#de£ine 


XtNdestroyCallback 


"destroyCallback" 


#define 


XtNeditType 


"editType" 


#def ine 


XtNfont 


"font" 


#define 


XtNforceBars 


"forceBars" 


#def ine 


XtN foreground 


foreground 


#define 


XtNfunction 


"function" 


#define 


XtNheight 


"height" 


#def ine 


XtNhSpace 


"hSpace" 


#define 


XtNindex 


"index" 


#def ine 


XtNinnerHeight 


"innerHeight" 


#define 


XtNinnerWidth 


"innerWidth" 


#define 


XtNinnerWindow 


"innerWindow" 


#define 


XtNinsertPosition 


"insertPosition" 


#def ine 


XtNinternalHeight 


"internalHeight" 


#define 


XtNinternalWidth 


"internalWidth" 


#def ine 


XtNjustify 


"justify" 


#define 


XtNknobHeight 


"knobHeight" 


#def ine 


XtNknoblndent 


"knob Indent" 


#define 


XtNknobPixel 


"knobPixel" 


#define 


XtNknobWidth 


"knobWidth" 


#define 


XtNlabel 


"label" 


#define 


XtNlength 


"length" 


#define 


XtNlowerRight 


"lowerRight" 


^define 


XtNmappedWhenManaged 


"mappedWhenManaged" 


#def ine 


XtNmenuEntry 


"menuEntry" 


#define 


XtNname 


"name" 


#def ine 


XtNnotify 


"notify" 
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#define XtNorientation 
#define XtNparameter 
#de£ine XtNpopupCallback 
#define XtNpopdownCallback 
#define XtNreverseVideo 
#define XtNscreen 
#define XtNscrollProc 
#define XtNscrollDCursor 
#define XtNscrollHCursor 
#define XtNscrollLCursor 
#define XtNscrollRCursor 
#define XtNscrollUCursor 
#define XtNscrollVCursor 
#define XtNselection 
#define XtNselectionArray 
#define XtNsensitive 
#define XtNshown 
#define XtNspace 
#define XtNstring 
#define XtNtextOptions 
#define XtNtextSink 
#define XtNtextSource 
#define XtNthickness 
#define XtNthumb 
#define XtNthumbProc 
#define XtNtop 
#define XtNtranslations 
#define XtNuseBottom 
#define XtNuseRight 
#define XtNvalue 
#define XtNvSpace 
#define XtNwidth 
#define XtNwindow 
#define XtNx 
#define XtNy 

/* Class types */ 

#define XtCAccelerators 
#define XtCBackground 
#define XtCBoolean 
#define XtCBorderColor 
#define XtCBorderWidth 
#define XtCCallback 
#define XtCColormap 
#define XtCColor 
#define XtCCursor 
#define XtCDepth 
#define XtCEditType 
#define XtCEventBindings 
#define XtCFile 
#define XtCFont 
#define XtCForeground 
#define XtCFraction 
#define XtCFunction 
#define XtCHeight 
#define XtCHSpace 



"orientation" 

"parameter" 

"popupCallback" 

"popdownCallback" 

"reverseVideo" 

"screen" 

"scrollProc" 

"scrollDownCursor" 

"scrollHorizontalCursor" 

"scrollLeftCursor" 

"scrollRightCursor" 

"scrollUpCursor" 

" scrollVerticalCursor " 

"selection" 

" selectionArray" 

"sensitive" 

" shown" 

"space" 

"string" 

"textOptions" 

"textSink" 

"textSource" 

"thickness" 

"thumb" 

"thumbProc" 

"top" 

"translations" 

"useBottom" 

"useRight" 

"value" 

"vSpace" 

"width" 

"window" 

"x" 

"y" 



"Accelerators" 

"Background" 

"Boolean" 

"BorderColor" 

"BorderWidth" 

"Callback" 

"Colormap" 

"Color" 

"Cursor" 

"Depth" 

"EditType" 

"EventBindings" 

"File" 

"Font" 

"Foreground" 

"Fraction" 

"Function" 

"Height" 

"HSpace" 
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#define XtCIndex 
#define XtCInterval 
#define XtC Justify 
#define XtCKnoblndent 
#define XtCKnobPixel 
#define XtCLabel 
#def ine XtCLength 
#define XtCMappedWhenManaged 
#define XtCMargin 
#define XtCMenuEntry 
#define XtCNotify 
#define XtCOrientation 
#define XtCParameter 
#define XtCPixmap 
#define XtCPosition 
#define XtCScreen 
#define XtCScrollProc 
#define XtCScrollDCursor 
#define XtCScrollHCursor 
#define XtCScrollLCursor 
#define XtCScrollRCursor 
#define XtCScrollUCursor 
#define XtCScrollVCursor 
#define XtCSelection 
#define XtCSensitive 
#define XtCSelectionArray 
#define XtCSpace 
#define XtCString 
#define XtCTextOptions 
#define XtCTextPosition 
#define XtCTextSink 
#define XtCTextSource 
#define XtCThickness 
#define XtCThumb 
#define XtCTranslations 
#define XtCValue 
#define XtCVSpace 
#define XtCWidth 
#define XtCWindow 
#define XtCX 
#define XtCY 

/* Representation types */ 

#define XtRAcceleratorTable 
#define XtRBoolean 
#define XtRCallback 
#define XtRCallProc 
#define XtRColor 
#define XtRCursor 
#define XtRDimension 
#define XtRDi splay 
#define XtREditMode 
#define XtRFile 
#define XtRFont 



"Index" 

"Interval" 

"Justify" 

"Knoblndent" 

"KnobPixel" 

"Label" 

"Length" 

"MappedWhenMan ag ed " 

"Margin" 

"MenuEntry" 

"Notify" 

"Orientation" 

"Parameter" 

"Pixmap" 

"Position" 

"Screen" 

"ScrollProc" 

"ScrollDownCursor" 

"ScrollHorizontalCursor" 

"ScrollLeftCursor" 

"ScrollRightCursor" 

"ScrollUpCursor" 

"ScrollVerticalCursor" 

"Selection" 

"Sensitive" 

"SelectionArray" 

"Space" 

"String" 

"TextOptions" 

"TextPosition" 

"TextSink" 

"TextSource" 

"Thickness" 

"Thumb" 

"Translations" 

"Value" 

"VSpace" 

"Width" 

"Window" 

"X" 

"Y" 



"AcceleratorTable" 

"Boolean" 

"Callback" 

"CallProc" 

"Color" 

"Cursor" 

"Dimension" 

"Display" 

"EditMode" 

"File" 

"Font" 
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#define XtRFontStruct 
#define XtRFunction 
#define XtRGeometry 
#define XtRImmediate 
yWefine XtRInt 
#define XtRJustify 
#define XtRLongBoolean 
#define XtROrientation 
#define XtRPixel 
#define XtRPixmap 
#define XtRPointer 
y/define XtRPosition 
#define XtRShort 
#define XtRString 
#define XtRStringTable 
#de£ine XtRUnsignedChar 
y/define XtRTranslationTable 
yjtdefine XtRWindow 



"FontStruct" 

"Function" 

"Geometry" 

"Immediate" 

"Int" 

"Justify" 

"LongBoolean" 

"Orientation" 

"Pixel" 

"Pixmap" 

"Pointer" 

"Position" 

"Short" 

"String" 

"StringTable" 

"UnsignedChar" 

"TranslationTable' 

"Window" 



/* Boolean enumeration constants */ 

y/define XtEoff "off" 

y/define XtEfalse "false" 

y/define XtEno "no" 

y/define XtEon "on" 

y/define XtEtrue "true" 

y/define XtEyes "yes" 

/* Orientation enumeration constants */ 

y/define XtEvertical "vertical" 
y/define XtEhorizontal "horizontal" 

/* text edit enumeration constants */ 

y/define XtEtextRead "read" 
y/define XtEtextAppend "append" 
#define XtEtextEdit "edit" 

/* color enumeration constants */ 

y/define XtExtdef aultbackground "xtdef aultbackground" 
y/define XtExtdef aultforeground "xtdef aultforeground" 

/* font constant */ 

y/define XtExtdef aultfont "xtdef aultfont" 



E - 4 StringDefs.h Header File 



Reference Information 



This section contrains reference information about the Xt Intrinsics included with the X 
Window System. The entries are arranged aphabetically, with each entry starting on its 
own "page 1." 



Function 

MenuPopdown 

MenuPopup 

XtAddCallback 

XtAddCallbacks 

XtAddEventHandler 

XtAddExposureToRegion 

XtAddGrab 

XtAddRawEventHandler 

XtAppAddActions 

XtAppAddConverter 

XtAppAddlnput 

XtAppAddTimeOut 

XtAppAddWorkProc 

XtAppCreateShell 

XtAppError 

XtAppErrorMsg 

XtAppGetErrorDatabase 

XtAppGetErrorDatabaseText 

XtAppGetSelectionTimeout 

XtAppMainLoop 

XtAppNextEvent 

XtAppPeekEvent 

XtAppPending 

XtAppProcessEvent 

XtAppSetErrorHandler 

XtAppSetErrorMsgHandler 

XtAppSetSelectionTimeout 

XtAppSetWarningHandler 



Location 



XtPopdown(3X) 

XtPopup(3X) 

XtAddCallback(3X) 

XtAddCallback(3X) 

XtAddEventHandler(3X) 

XtAddExposureToRegion(3X) 

XtAddGrab(3X) 

XtAddEventHandler(3X) 

XtAppAddActions(3X) 

XtAppAddConverter(3X) 

XtAppAddInput(3X) 

XtAppAddTimeOut(3X) 

XtAppAddWorkProc(3X) 

XtAppCreateShell(3X) 

XtAppError(3X) 

XtAppErrorMsg(3X) 

XtAppGetErrorDatabase(3X) 

XtAppGetErrorDatabase(3X) 

XtAppGetSelectionTimeout(3X) 

XtAppNextEvent(3X) 

XtAppNextEvent(3X) 

XtAppNextEvent(3X) 

XtAppNextEvent(3X) 

XtAppNextEvent(3X) 

XtAppError(3X) 

XtAppErrorMsg(3X) 

XtAppGetSelectionTimeout(3X) 

XtAppError(3X) 
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Function 


Location 


XtAppSetWarningMsgHandler 


XtAppErrorMsg(3X) 


XtAppWarningMsg 


XtAppErrorMsg(3X) 


XtAugmentTranslations 


XtParseTranslationTable(3X) 


XtBuildEventMask 


X/iT* M 1T~"» a "fc J* 1 /^*V7"\ 

XtBuildEventMask(3X) 


XtCalLAcceptFocus 


XtCalLAcceptFocus(3X) 


XtCallbackExclusive 


XtPopup(3X) 


X/i-O 111 1\T 

XtCallbackNone 


XtPopup(3X) 


-XT-jaT^ 111 1 XT 1 * 

XtCallbackNonexclusive 


XtPopup(3X) 


XtCallbackPopdown 


XtPopdown(3X) 


XtCallCallbacks 


■v/"j.y^ it at-% 111_ 1 v\ 

XtCallCallbacks(3X) 


XtCalloc 


XtMalloc(3X) 


XtCheckSubclass 


XtClass(3X) 


XtClass 


XtClass(3X) 


XtCloseDisplay 


XtDisplayInitialize(3X) 


XtConhgureWidget 


XtConfigureWidget(3X) 


XtConvert 


XtConvert(3X) 


XtConvertCase 


XtSetKeyTranslator(3X) 


XtCreateApplicationContext 


XtCreateApplicationContext(3X) 


XtCreateManagedWidget 


XtCreateWidget(3X) 


XtCreatePopupShell 


XtCreatePopupSnell(3X) 


XtCreatewidget 


XtCreateWidget(3X) 


XtCreateWindow 


ViO a. TT 7* J //>'V7"\ 

XtCreateWindow(3X) 


XtDatabase 


XtDisplayInitialize(3X) 


XtDestroyApplicationContext 


XtCreateApplicationContext(3X) 


XtDestroyWidget 


XtCreateWidget(3X) 


XtDirectConvert 


XtConvert(3X) 


XtDisownSelection 


XtOwnSelection(3X) 


XtDispatchEvent 


XtAppNextEvent(3X) 


XtDisplay 


XtDisplay(3X) 


XtDisplaylnitialize 


XtDisplayInitialize(3X) 


XtFree 


XtMalloc(3X) 


XtGetApplicationResources 


XtGetSubresources(3X) 


XtGetGC 


XtGetGC(3X) 


XtGetResourceList 


XtGetResourceList(3X) 


XtGetSelectionValue 


XtGetSelectionValue(3X) 


XtGetSelectionValues 


XtGetSelectionValue(3X) 


XtGetSelectionValuesIncremental 


XtGetSelectionValue(3X) 


XtGetSubresources 


XtGetSubresources(3X) 
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Fiinrfion 


I^fwatinn 


XtGetSubvalues 


XtSetValues(3X) 


XtGetValues 


XtSetValues(3X) 


XtGrabKey 


XtGrabKeyboard(3X) 


XtGrabKeyboard 


XtGrabKeyboard(3X) 


XtHasCallbacks 


XtCallCallbacks(3X) 


Xtlnitialize 


XtInitialize(3X) 


XtlnstallAccelerators 


XtParseAcceleratorTable(3X) 


XtlnstallAllAccelerators 


XtParseAcceleratorTable(3X) 


XtlsComposite 


XtClass(3X) 


XtlsManaged 


XtClass(3X) 


XtlsRealized 


XtRealizeWidget(3X) 


XtlsSensitive 


XtSetSensitive(3X) 


XtlsSubclass 


XtClass(3X) 


XtMakeGeometryRequest 


XtMakeGeometryRequest(3X) 


XtMakeResizeRequest 


XtMakeGeometryRequest(3X) 


XtMalloc 


XtMalloc(3X) 


XtMapWidget 


XtMapWidget(3X) 


XtManageChild 


XtManageChildren(3X) 


XtManageChildren 


XtManageChildren(3X) 


XtMergeArgLists 


XtSetArg(3X) 


XtMoveWidget 


XtConfigureWidget(3X) 


XtNameToWidget 


XtNameToWidget(3X) 


XtNew 


XtMalloc(3X) 


XtNewString 


XtMalloc(3X) 


XtNumber 


XtOffset(3X) 


XtOffset 


XtOffset(3X) 


XtOpenDisplay 


XtDisplayInitialize(3X) 


XtOverrideTranslations 


XtParseTranslationTable(3X) 


XtOwnSelection 


XtOwnSelection(3X) 


XtParent 


XtDisplay(3X) 


XtParseAcceleratorTable 


XtParseAcceleratorTable(3X) 


XtParseTranslationTable 


XtParseTranslationTable(3X) 


XtPopdown 


XtPopdown(3X) 


XtPopup 


XtPopup(3X) 


XtQueryGeometry 


AtvjueryLjeonieiry^A. ) 


XtRealizeWidget 


XtRealizeWidget(3X) 


XtRealloc 


XtMalloc(3X) 


XtRegisterCaseConverter 


XtSetKeyTranslator(3X) 
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Function 


Location 


XtReleaseGC 


XtGetGC(3X) 


XtRemoveAHCallbacks 


XtAddCallback(3X) 


XtRemoveCallback 


XtAddCallback(3X) 


XtRemoveCallbacks 


XtAddCallback(3X) 


XtRemoveEventHandler 


XtAddEventHandler(3X) 


XtRemoveGrab 


XtAddGrab(3X) 


XtR em ovelnput 


XtAppAddInput(3X) 


XtRemoveRawEventHandler 


XtAddEventHandler(3X) 


XtRemoveTimeOut 


XtAppAddTimeOut(3X) 


XtRemoveWorkProc 


XtAppAddWorkProc(3X) 


XtResizeWidget 


XtConfigureWidget(3X) 


XtScreen 


XtDisplay(3X) 


XtSetArg 


XtSetArg(3X) 


XtSetKevboardFocus 


XtSetKeyboardFocus(3X) 


XtSetKeyTranslator 


XtSetKeyTranslator(3X) 


XtSetMappedWhenManaged 


XtMapWidget(3X) 


XtSetSensitive 


XtSetSensitive(3X) 


XtSetSubvalues 


XtSetValues(3X) 


XtSetValues 


XtSetValues(3X) 


XtStringConversionWarning 


XtStringConversionWarning(3X) 


XtSuperClass 


XtClass(3X) 


XtToolkitlnitialize 


XtCreateApplicationContext(3X) 


XtTranslateCoordinates 


XtTranslateCoordinates(3X) 


XtTranslateKeycode 


XtSetKeyTranslator(3X) 


XtUngrabKey 


XtUngrabKey(3X) 


XtUngrabKeyboard 


XtUngrabKeyboard(3X) 


XtUninstallTranslations 


XtParseTranslationTable(3X) 


XtUnm anageChild 


XtManageChildren(3X) 


XtUnmanageChildren 


XtManageChildren(3X) 


XtUnmapWidget 


XtMapWidget(3X) 


XtUnrealizeWidget 


XtRealizeWidget(3X) 


XtWidgetCallbacks 


XtWidgetCallbacks(3X) 


XtWidgetHasCallbacks 


XtWidgetHasCallbacks(3X) 


XtWidgetToApplicationContext 


XtCreateApplicationContext(3X) 


XtWidgetToWindow 


XtNameToWidget(3X) 


XtWindow 


XtDisplay(3X) 
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XtAddCalIback(3X) 



Series 300 and 800 Only 



XtAddCallback(3X) 



NAME 

XtAddCallback, XtAddCallbacks, XtRemoveCallback, XtRemoveCallbacks, 
XtRemoveAllCallbacks - add and remove callback procedures 

SYNTAX 

void XtAddCallback(H>, callback jiame, callback, client jiata) 
Widget w; 

String callback jtame; 
XtCallbackProc callback; 
caddr_t client jiata; 
void XtAddCallbacks^, callback jiame, callbacks) 
Widget w; 

String callback jtame; 
XtCallbackList callbacks; 
void XtRemoveCallback(M>, callback jiame, callback, client jiata) 
Widget w; 

String callback jtame; 
XtCallbackProc callback; 
caddr_t client jiata; 
void XtRemoveCallbacks^, callback jtame, callbacks) 
Widget w; 

String callback jiame; 
XtCallbackList callbacks; 
void XtRemoveAllCallbacks(H', callback jiame) 
Widget w; 

String callback jtame; 
ARGUMENTS 

callback Specifies the callback procedure. 

callbacks Specifies the null-terminated list of callback procedures and corresponding 

client data. 

callback jtame Specifies the callback list to which the procedure is to be appended or 
deleted. 

client jiata Specifies the argument that is to be passed to the specified procedure when 

it is invoked by XtCallbacks or NULL, or the client data to match on the 
registered callback procedures. 

w Specifies the widget. 

DESCRIPTION 

The XtAddCallback function adds the specified callback procedure to the specified widget's 
callback list. The XtAddCallbacks add the specified list of callbacks to the specified widget's 
callback list. The XtRemoveCallback function removes a callback only if both the procedure and 
the client data match. The XtRemoveCallbacks function removes the specified callback 
procedures from the specified widget's callback list. The XtRemoveAllCallbacks function 
removes all the callback procedures from the specified widget's callback list. 

SEE ALSO 

XtCallCallbacks(3X) 
Programming with Xlib 
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XtAddEventHandler (3X) 



NAME 

XtAddEventHandler, XtAddRawEventHandler, XtRemoveEventHandler 
XtRemoveRawEventHandler - add and remove event handlers 

SYNTAX 

void XtAddEventHandler^, event jnask, nonmaskable, proc, client jiata) 
Widget w; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client _data; 

void XtAddRawEventHandler(H>, event jnask, nonmaskable, proc, client jiata) 
Widget w; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client jiata; 

void XtRemoveEventHandler^, event jnask, nonmaskable, proc, client jiata) 
Widget w; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client jiata; 

void XtRemoveRawEventHandler(H', event jnask, nonmaskable, proc, client jiata) 
Widget w; 

EventMask event jnask; 
Boolean nonmaskable; 
XtEventHandler proc; 
caddr_t client jiata; 

ARGUMENTS 

client jiata Specifies additional data to be passed to the client's event handler. 

event jnask Specifies the event mask for which to call or unregister this procedure. 

nonmaskable Specifies a Boolean value that indicates whether this procedure should be 

called or removed on the nonmaskable events (GraphicsExpose, NoExpose, 
SelectionCIear, Select ionRequest, SelectionNotify, ClientMessage, and 
MappingNotify). 

proc Specifies the procedure that is to be added or removed. 

w Specifies the widget for which this event handler is being registered. 

DESCRIPTION 

The XtAddEventHandler function registers a procedure with the dispatch mechanism that is to be 
called when an event that matches the mask occurs on the specified widget. If the procedure is 
already registered with the same client_data, the specified mask is ORed into the existing mask. If 
the widget is realized, XtAddEventHandler calls XSelectlnput, if necessary. The 
XtAddRawEventHandler function is similar to XtAddEventHandler except that it does not affect 
the widget's mask and never causes an XSelectlnput for its events. Note that the widget might 
already have those mask bits set because of other nonraw event handlers registered on it. The 
XtAddRawEventHandler function is similar to XtAddEventHandler except that it does not affect 
the widget's mask and never causes an XSelectlnput for its events. Note that the widget might 
already have those mask bits set because of other nonraw event handlers registered on it. The 
XtRemoveRawEventHandler function stops the specified procedure from receiving the specified 
events. Because the procedure is a raw event handler, this does not afifect the widget's mask and 
never causes a call on XSelectlnput. 

SEE ALSO 

XtAppNextEvent(3X),XtBuildEventMask(3X) 
Programming with Xlib 
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NAME 

XtAddExposureToRegion - merge exposure events into a region 

SYNTAX 

void XtAddExposureToRegion(eve/tf, region) 
XEvent *event; 
Region region; 

ARGUMENTS 

event Specifies a pointer to the Expose or GraphicsExpose event. 

region Specifies the region object (as defined in <X11/Xutil.h>). 

DESCRIPTION 

The XtAddExposureToRegion function computes the union of the rectangle defined by the 
exposure event and the specified region. Then, it stores the results back in region. If the event 
argument is not an Expose or GraphicsExpose event, XtAddExposureToRegion returns without 
an error and without modifying region. This function is used by the exposure compression 
mechanism (see Section 7.9.3). 

SEE ALSO 

Programming with Xlib 
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NAME 

XtAddGrab, XtRemoveGrab - redirect user input to a modal widget 

SYNTAX 

void XtAddGrab(H>, exclusive, spring loaded) 

Widget h>; 

Boolean exclusive; 

Boolean spring loaded; 
void XtRemoveGrab(w) 

Widget w; 

ARGUMENTS 

exclusive Specifies whether user events should be dispatched exclusively to this widget 

or also to previous widgets in the cascade. 

springjoaded Specifies whether this widget was popped up because the user pressed a 
pointer button. 

w Specifies the widget to add to or remove from the modal cascade. 

DESCRIPTION 

The XtAddGrab function appends the widget (and associated parameters) to the modal cascade 
and checks that exclusive is True if springjoaded is True. If these are not True, XtAddGrab 
generates an error. The modal cascade is used by XtDispatchEvent when it tries to dispatch a 
user event. When at least one modal widget is in the widget cascade, XtDispatchEvent first 
determines if the event should be delivered. It starts at the most recent cascade entry and follows 
the cascade up to and including the most recent cascade entry added with the exclusive parameter 
True. This subset of the modal cascade along with all descendants of these widgets comprise the 
active subset. User events that occur outside the widgets in this subset are ignored or remapped. 
Modal menus with submenus generally add a submenu widget to the cascade with exclusive False. 
Modal dialog boxes that need to restrict user input to the most deeply nested dialog box add a 
subdialog widget to the cascade with exclusive True. User events that occur within the active 
subset are delivered to the appropriate widget, which is usually a child or further descendant of 
the modal widget. Regardless of where on the screen they occur, remap events are always 
delivered to the most recent widget in the active subset of the cascade that has springjoaded 
True, if any such widget exists. The XtRemoveGrab function removes widgets from the modal 
cascade starting at the most recent widget up to and including the specified widget. It issues an 
error if the specified widget is not on the modal cascade. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtAppAddActions - register an action table 

SYNTAX 

void XtAppAddActions(qp/?_co/tfetf, actions, num_actions) 
XtAppContext app_context; 
XtActionList actions; 
Cardinal num_actions; 

ARGUMENTS 

app_context Specifies the application context. 

actions Specifies the action table to register. 

numjargs Specifies the number of entries in this action table. 

DESCRIPTION 

The XtAppAddActions function adds the specified action table and registers it with the translation 
manager. 

SEE ALSO 

XtParseTranslationTable(3X) 
Programming with Xlib 
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NAME 

XtAppAddConverter - register resource converter 

SYNTAX 

void XtAppAddConvertet(appjx)ntext, fromjype, tojype, converter, convert _args, num_args) 
XtAppContext app_context; 
String fromjype; 
String tojype; 
XtConverter converter, 
XtConvertArgList convert jtrgs; 
Cardinal numargs; 

ARGUMENTS 

app_context Specifies the application context. 

converter Specifies the type converter procedure. 

convert_args Specifies how to compute the additional arguments to the converter or 

NULL. 

fromjype Specifies the source type. 

numjzrgs Specifies the number of additional arguments to the converter or zero. 

tojype Specifies the destination type. 

DESCRIPTION 

The XtAppAddConverter registers a the specified resource converter. 
SEE ALSO 

XtConvert(3Xt), XtStringConversionWarning(3Xt) 
Programming with Xlib 
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NAME 

XtAppAddlnput, XtRemovelnput - register and remove an input source 

SYNTAX 

Xtlnputld XtAppAddlnput(app_context, source, condition, proc, client _datd) 

XtAppContext app_context; 

int source; 

caddr_t condition; 

XtlnputCallbackProc proc; 

caddr_t client _data; 
void XtRemoveInput(id) 

Xtlnputld id; 

ARGUMENTS 

appjcontext Specifies the application context that identifies the application. 

client _data Specifies the argument that is to be passed to the specified procedure when 

input is available. 

condition Specifies the mask that indicates a read, write, or exception condition or 

some operating system dependent condition. 

id Specifies the ID returned from the corresponding XtAppAddlnput call. 

proc Specifies the procedure that is to be called when input is available. 

source Specifies the source file descriptor on a UNIX-based system or other 

operating system dependent device specification. 

DESCRIPTION 

The XtAppAddlnput function registers with the X Toolkit Intrinsics read routine a new source of 
events, which is usually file input but can also be file output. Note that file should be loosely 
interpreted to mean any sink or source of data. XtAppAddlnput also specifies the conditions 
under which the source can generate events. When input is pending on this source, the callback 
procedure is called. The legal values for the condition argument are operating-system dependent. 
On a UNIX-based system, the condition is some union of XtlnputReadMask, XtlnputWriteMask, 
and XtlnputExceptMask. The XtRemovelnput function causes the X Toolkit Intrinsics read 
routine to stop watching for input from the input source. 

SEE ALSO 

XtAppAddTimeOut(3X) 
Programming with Xlib 
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NAME 

XtAppAddTimeOut, XtRemoveTimeOut - register and remove timeouts 

SYNTAX 

Xtlntervalld XtAppAddTimeOut(<ap/>_c0«tetf, interval, proc, client JLatd) 

XtAppContext app_context; 

unsigned long interval; 

XtTimerCallbackProc proc, 

caddr_t client _data; 
void XtRemoveTimeOut(ri/M«r) 

Xtlntervalld timer, 

ARGUMENTS 

app_context Specifies the application context for which the timer is to be set. 

client _data Specifies the argument that is to be passed to the specified procedure when . 

interval Specifies the time interval in milliseconds. 

proc Specifies the procedure that is to be called when time expires. 

timer Specifies the ID for the timeout request to be destroyed. 

DESCRIPTION 

The XtAppAddTimeOut function creates a timeout and returns an identifier for it. The timeout 
value is set to interval. The callback procedure is called when the time interval elapses, and then 
the timeout is removed. The XtRemoveTimeOut function removes the timeout. Note that 
timeouts are automatically removed once they trigger. 

SEE ALSO 

XtAppAddInput(3X) 
Programming with Xlib 
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NAME 



XtAppAddWorkProc, XtRemoveWorkProc - Add and remove background processing procedures 



XtWorkProcId XtAppAd6WotkPtoc(app_context,proc, client _data) 

XtAppContext app_context; 

XtWorkProc proc; 

caddr_t client _data; 
void XtRemoveW6rkProc(w/) 

XtWorkProcId id; 



DESCRIPTION 

The XtAppAddWorkProc function adds the specified work procedure for the application 
identified by app_context. The XtRemoveWorkProc function explicitly removes the specified 
background work procedure. 

SEE ALSO 

XtAppNextEvent(3X) 
Programming with Xlib 
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SYNTAX 



ARGUMENTS 



proc 
id 



app_context 
client data 



Specifies the application context that identifies the application. 

Specifies the argument that is to be passed to the specified procedure when 
it is called. 

Specifies the procedure that is. 

Specifies which work procedure to remove. 
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NAME 

XtAppCreateShell - create top-level widget instance 

SYNTAX 

Widget XtAppCreateShell(<5?p/icaft'o»_name, application jlass, widget jlass, display, 
orgs, num jags) 
String application jtame; 
String application jlass', 
WidgetClass widget jlass; 
Display 'display; 
ArgList orgs; 
Cardinal num jags; 

ARGUMENTS 

application jlass Specifies 

application jtame Specifies 
orgs Specifies 
display Specifies 
num jugs Specifies 
widget jlass Specifies 
DESCRIPTION 

The XtAppCreateShell function saves the specified application name and application class for 
qualifying all widget resource specifiers. The application name and application class are used as 
the left-most components in all widget resource names for this application. XtAppCreateShell 
should be used to create a new logical application within a program or to create a shell on another 
display. In the first case, it allows the specification of a new root in the resource hierarchy. In the 
second case, it uses the resource database associated with the other display. Note that the widget 
returned by XtAppCreateShell has the WM_COMMAND property set for session managers (see 
Chapter 4). 

SEE ALSO 

XtCreateWidget(3X) 
Programming with Xlib 



the class name of this application, 
the name of the application instance. 

the argument list in which to set in the WM_COMMAND property. 

the display from which to get the resources. 

the number of arguments in the argument list. 

the widget class that the application top-level widget should be. 
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NAME 

XtAppError, XtAppSetErrorHandler, XtAppSetWarningHandler, XtAppWarning - low-level 
error handlers 

SYNTAX 

void XtAppError(app_context, message) 

XtAppContext app_context; 

String message; 
void XtAppSetErrorHandler(^?_co«tetf , handler) 

XtAppContext app_context; 

XtErrorHandler handler, 
void XtAppSetWarningHandter(qp>p_coMtetf , handler) 

XtAppContext app_context; 

XtErrorHandler handler, 
void XtAppWaming(*5>/>_co/tfetf, message) 

XtAppContext app_context; 

String message; 

ARGUMENTS 

app_context Specifies the application context. 

message Specifies the nonfatal error message that is to be reported. 

handler Specifies the new fatal error procedure, which should not return, or the 

nonfatal error procedure, which usually returns. 

message Specifies the message that is to be reported. 

DESCRIPTION 

The XtAppError function calls the installed error procedure and passes the specified message. 
The XtAppSetErrorHandler function registers the specified procedure, which is called when a 
fatal error condition occurs. The XtAppSetWarningHandler registers the specified procedure, 
which is called when a nonfatal error condition occurs. The XtAppWarning function calls the 
installed nonfatal error procedure and passes the specified message. 

SEE ALSO 

XtAppGetErrorDatabase(3X), XtAppErrorMsg(3X) 
Programming with Xlib 
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NAME 

XtAppErrorMsg, XtAppSetErrorMsgHandler, XtAppSetWarningMsgHandler, 
XtAppWarningMsg - high-level error handlers 

SYNTAX 

void XtAppErtOTMsg(app_context, name, type, class, default, params, num jparams) 

XtAppContext app_context; 

String name; 

String type; 

String class; 

String default; 

String * params; 

Cardinal *num _params; 
void XtAppSetErrorMsgHandler(qp/>_contetf, msg handler) 
XtAppContext app_context; 
XtErrorMsgHandler msgjiandler, 
void XtAppSetWamingMsgHandler(<5>/>_C0«tetf , msgjiandler) 
XtAppContext app_context; 
XtErrorMsgHandler msgjiandler, 
void XtAppWamingMsg(<jpp_co/«etf, name, type, class, default, params, num _params) 

XtAppContext appjontext; 

String name; 

String type; 

String class; 

String default; 

String *params; 

Cardinal *num _params; 

ARGUMENTS 

app_context Specifies the application context. 

class Specifies the resource class. 

default Specifies the default message to use. 

name Specifies the general kind of error. 

type Specifies the detailed name of the error. 

msgjandler Specifies the new fatal error procedure, which should not return or the 
nonfatal error procedure, which usually returns. 

num _params Specifies the number of values in the parameter list. 

params Specifies a pointer to a list of values to be stored in the message. 

DESCRIPTION 

The XtAppErrorMsg function calls the high-level error handler and passes the specified 
information. The XtAppSetErrorMsgHandler function registers the specified procedure, which 
is called when a fatal error occurs. The XtAppSetWarningMsgHandler function registers the 
specified procedure, which is called when a nonfatal error condition occurs. The 
XtAppWarningMsg function calls the high-level error handler and passes the specified 
information. 

SEE ALSO 

XtAppGetErrorDatabase(3X), XtAppError(3X) 
Programming with Xlib 
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NAME 

XtAppGetErrorDatabase, XtAppGetErrorDatabaseText - obtain error database 

SYNTAX 

XrmDatabase *XtAppGetErrorDatabase(qpp_co/tfetf) 

XtAppContext app_context; 
void XtAppGetErrorDatabaseText^^ j?ontetf, name, type, class, default, buffer return, nbytes, 
database') 

XtAppContext app_context; 

char *name, *type, *class; 

char *default; 

char * buffer return; 

int nbytes; 

XrmDatabase database; 
ARGUMENTS 

app_context Specifies the application context. 

buffer return Specifies the buffer into which the error message is to be returned. 

class Specifies the resource class of the error message. 

database Specifies the name of the alternative database that is to be used or NULL if 

the application's database is to be used. 

default Specifies the default message to use. 

name 

type Specifies the name and type that are concatenated to form the resource 

name of the error message. 

nbytes Specifies the size of the buffer in bytes. 

DESCRIPTION 

The XtAppGetErrorDatabase function returns the address of the error database. The X Toolkit 
Intrinsics do a lazy binding of the error database and do not merge in the database file until the 
first call to XtAppGetErrorDatbaseText. The XtAppGetErrorDatabaseText returns the 
appropriate message from the error database or returns the specified default message if one is not 
found in the error database. 

SEE ALSO 

XtAppError(3X), XtAppErrorMsg(3X) 
Programming with Xlib 
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NAME 

XtAppGetSelectionTimeout, XtAppSetSelectionTimeout- set and obtain selection timeout values 

SYNTAX 

unsigned long XtAppGetSelectionTimeout(^p jco/tfetf) 

XtAppContext app_context; 
void XtAppSetSelecticmTimeout(opp jrontetf, timeout) 

XtAppContext app_context; 

unsigned long timeout; 

ARGUMENTS 

app_context Specifies the application context. 

timeout Specifies the selection timeout in milliseconds. 

DESCRIPTION 

The XtAppGetSelectionTimeout function returns the current selection timeout value, in 
milliseconds. The selection timeout is the time within which the two communicating applications 
must respond to one another. The initial timeout value is set by the selectionTimeout application 
resource, or, if selectionTimeout is not specified, it defaults to five seconds. The 
XtAppSetSelectionTimeout function sets the X Toolkit Intrinsics 's selection timeout mechanism. 
Note that most applications should not set the selection timeout. 

SEE ALSO 

XtOwnSelection(3X) 
Programming with Xlib 



Hewlett-Packard Company 



-1- 



Jul 16, 1989 



XtAppNextEvent(3X) 



Series 300 and 800 Only 



XtAppNextEvent (3X) 



NAME 

XtAppNextEvent, XtAppPending, XtAppPeekEvent, XtAppProcessEvent, XtDispatchEvent, 
XtAppMainLoop - query and process events and input 

SYNTAX 

void XtAppNextEvent(ap/>_c0ntetf , event return) 

XtAppContext app_context; 

XEvent * event return; 
Boolean XtAppPeekEvent(ap/>_awtetf , event return) 

XtAppContext app_context; 

XEvent * event return; 
XtlnputMask XtAppPending(qp/> context) 

XtAppContext app_context; 
void XtAppProcessEvent(ap/>_co/tfe#, mask) 

XtAppContext app _context; 

XtlnputMask mask, 
Boolean XtDispatchEvent(eve/tf) 

XEvent *event; 
void XtAppMainLoop^/* context) 

XtAppContext app_context; 

ARGUMENTS 

app_context Specifies the application context that identifies the application . 

event Specifies a pointer to the event structure that is to be dispatched to the 

appropriate event handler. 

event jeturn Returns the event information to the specified event structure. 

mask Specifies what types of events to process. The mask is the bitwise inclusive 

OR of any combination of XtlMXEvent, XtlMTimer, and 
XtlMAlternatelnput. As a convenience, the X Toolkit defines the symbolic 
name XtlMAll to be the bitwise inclusive OR of all event types. 

DESCRIPTION 

If no input is on the X input queue, XtAppNextEvent flushes the X output buffer and waits for an 
event while looking at the other input sources and timeout values and calling any callback 
procedures triggered by them. This wait time can be used for background processing (see Section 
7.8). If there is an event in the queue, XtAppPeekEvent fills in the event and returns a nonzero 
value. If no X input is on the queue, XtAppPeekEvent flushes the output buffer and blocks until 
input is available (possibly calling some timeout callbacks in the process). If the input is an event, 
XtAppPeekEvent fills in the event and returns a nonzero value. Otherwise, the input is for an 
alternate input source, and XtAppPeekEvent returns zero. The XtAppPending function returns a 
nonzero value if there are events pending from the X server, timer pending, or other input sources 
pending. The value returned is a bit mask that is the OR of XtlMXEvent, XtlMTimer, and 
XtlMAlternatelnput (see XtAppProcessEvent). If there are no events pending, XtAppPending 
flushes the output buffer and returns zero. The XtAppProcessEvent function processes one timer, 
alternate input, or X event. If there is nothing of the appropriate type to process, 
XtAppProcessEvent blocks until there is. If there is more than one type of thing available to 
process, it is undefined which will get processed. Usually, this procedure is not called by client 
applications (see XtAppMainLoop). XtAppProcessEvent processes timer events by calling any 
appropriate timer callbacks, alternate input by calling any appropriate alternate input callbacks, 
and X events by calling XtDispatchEvent. When an X event is received, it is passed to 
XtDispatchEvent, which calls the appropriate event handlers and passes them the widget, the 
event, and client-specific data registered with each procedure. If there are no handlers for that 
event registered, the event is ignored and the dispatcher simply returns. The order in which the 
handlers are called is undefined. The XtDispatchEvent function sends those events to the event 
handler functions that have been previously registered with the dispatch routine. 
XtDispatchEvent returns True if it dispatched the event to some handler and False if it found no 
handler to dispatch the event to. The most common use of XtDispatchEvent is to dispatch events 
acquired with the XtAppNextEvent procedure. However, it also can be used to dispatch user- 
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constructed events. XtDispatchEvent also is responsible for implementing the grab semantics for 
XtAddGrab. The XtAppMainLoop function first reads the next incoming X event by calling 
XtAppNextEvent and then it dispatches the event to the appropriate registered procedure by 
calling XtDispatchEvent. This constitutes the main loop of X Toolkit applications, and, as such, it 
does not return. Applications are expected to exit in response to some user action. There is 
nothing special about XtAppMainLoop; it is simply an infinite loop that calls XtAppNextEvent 
and then XtDispatchEvent. Applications can provide their own version of this loop, which tests 
some global termination flag or tests that the number of top-level widgets is larger than zero 
before circling back to the call to XtAppNextEvent. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtBuildEventMask - retrieve a widget's event mask 

SYNTAX 

EventMask XtBuildEventMaskOv) 
Widget w; 

ARGUMENTS 

w Specifies the widget. 

DESCRIPTION 

The XtBuildEventMask function returns the event mask representing the logical OR of all event 
masks for event handlers registered on the widget with XtAddEventHandler and all event 
translations, including accelerators, installed on the widget This is the same event mask stored 
into the XSetWindowAttributes structure by XtRealizeWidget and sent to the server when event 
handlers and translations are installed or removed on the realized widget. 

SEE ALSO 

XtAddEventHandler(3X) 
Programming with Xlib 
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NAME 

XtCallAcceptFocus - call a widget's accept_focus procedure 

SYNTAX 

Boolean XtCallAcceptFocus^, time) 
Widget w; 
Time *time; 

ARGUMENTS 

time Specifies the X time of the event that is causing the accept focus. 

w Specifies the widget. 

DESCRIPTION 

The XtCallAcceptFocus function calls the specified widget's accept_focus procedure, passing it the 
specified widget and time, and returns what the accept_focus procedure returns. If accept_focus is 
NULL, XtCallAcceptFocus returns False. 

SEE ALSO 

XtSetKeyboardFocus(3X) 
Programming with Xlib 
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Series 300 and 800 Only 



NAME 



XtCallCallbacks, XtHasCallbacks - process callbacks 



SYNTAX 



void XtCallCallbacks(H>, cailbackjtame, call jJata) 
Widget w; 

String cailbackjtame; 
caddr_t calljiata; 

typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus; 

XtCallbackStatus XtHasCallbacks(H>, cailbackjtame) 
Widget h>; 

String cailbackjtame; 



DESCRIPTION 

The XtCallCallbacks function calls each procedure that is registered in the specified widget's 
callback list. The XtHasCallbacks function first checks to see if the widget has a callback list 
identified by callback_name. If the callback list does not exist, XtHasCallbacks returns 
XtCallbackNoList. If the callback list exists but is empty, it returns XtCallbackHasNone. If the 
callback list exists and has at least one callback registered, it returns XtCallbackHasSome. 

SEE ALSO 

XtAddCallback(3X) 
Programming with Xlib 



ARGUMENTS 



callback name 



Specifies the callback list to be executed or checked. 

Specifies a callback-list specific data value to pass to each of the callback 
procedure in the list. 

Specifies the widget. 



call data 



w 
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NAME 

XtClass, XtSuperClass, XtlsSubclass, XtCheckSubclass, XtlsComposite, XtlsManaged - obtain 
and verify a widget's class 

SYNTAX 

WidgetClass XtClass^) 

Widget w; 
WidgetClass XtSuperclass^) 

Widget w; 
Boolean XtIsSubclass(M>, widget _class) 

Widget w; 

WidgetClass widget _class; 
void XtCheckSubclass(H>, widget _class, message) 
Widget w; 

WidgetClass widget _class; 

String message; 
Boolean XtlsComposite^) 

Widget w; 
Boolean XtIsManaged(n>) 
Widget w; 

ARGUMENTS 

w Specifies the widget. 

widget _class Specifies the widget class. 

message Specifies the message that is to be used. 

DESCRIPTION 

The XtClass function returns a pointer to the widget's class structure. The XtSuperclass function 
returns a pointer to the widget's superclass class structure. The XtlsSubclass function returns 
True if the class of the specified widget is equal to or is a subclass of the specified widget class. 
The specified widget can be any number of subclasses down the chain and need not be an 
immediate subclass of the specified widget class. Composite widgets that need to restrict the class 
of the items they contain can use XtlsSubclass to find out if a widget belongs to the desired class 
of objects. The XtCheckSubclass macro determines if the class of the specified widget is equal to 
or is a subclass of the specified widget class. The widget can be any number of subclasses down 
the chain and need not be an immediate subclass of the specified widget class. If the specified 
widget is not a subclass, XtCheckSubclass constructs an error message from the supplied 
message, the widget's actual class, and the expected class and calls XtErrorMsg. 
XtCheckSubclass should be used at the entry point of exported routines to ensure that the client 
has passed in a valid widget class for the exported operation. XtCheckSubclass is only executed 
when the widget has been compiled with the compiler symbol DEBUG defined; otherwise, it is 
defined as the empty string and generates no code. The XtlsComposite function is a convenience 
function that is equivalent to XtlsSubclass with compositeWidgetClass specified. The 
XtlsManaged macro (for widget programmers) or function (for application programmers) returns 
True if the specified child widget is managed or False if it is not. 

SEE ALSO 

XtAppErrorMsg(3X), XtDisplay(3X) 
Programming with Xlib 
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NAME 

XtConfigureWidget, XtMoveWidget, XtResizeWidget - move and resize widgets 

SYNTAX 

void XtConfigureWidget^, x,y, width, height, border jvidth) 

Widget w; 

Positions; 

Position y; 

Dimension width; 

Dimension height; 

Dimension border width; 
void XtMoveWidgetOv,*,^) 

Widget w; 

Position*; 

Position y; 

void XtResizeWidget(»v, width, height, border jvidth) 

Widget w; 

Dimension width; 

Dimension height; 

Dimension border jvidth; 
void XtResizeWindow(H>) 

Widget h>; 

ARGUMENTS 
width 
height 

border jvidth Specify the new widget size. 

w Specifies the widget. 

x 

y Specify the new widget x and y coordinates. 

DESCRIPTION 

The XtConfigureWidget function returns immediately if the specified geometry fields are the 
same as the old values. Otherwise, XtConfigureWidget writes the new x, y, width, height, and 
borderwidth values into the widget and, if the widget is realized, makes an Xlib 
XConf igureWindow call on the widget's window. If either the new width or height is different 
from its old value, XtConfigureWidget calls the widget's resize procedure to notify it of the size 
change; otherwise, it simply returns. The XtMoveWidget function returns immediately if the 
specified geometry fields are the same as the old values. Otherwise, XtMoveWidget writes the 
new x and y values into the widget and, if the widget is realized, issues an Xlib XMoveWindow call 
on the widget's window. The XtResizeWidget function returns immediately if the specified 
geometry fields are the same as the old values. Otherwise, XtResizeWidget writes the new width, 
height, and border width values into the widget and, if the widget is realized, issues an 
XConfigureWindow call on the widget's window. If the new width or height are different from the 
old values, XtResizeWidget calls the widget's resize procedure to notify it of the size change. The 
XtResizeWindow function calls the XConfigureWindow Xlib function to make the window of the 
specified widget match its width, height, and border width. This request is done unconditionally 
because there is no way to tell if these values match the current values. Note that the widget's 
resize procedure is not called. There are very few times to use XtResizeWindow; instead, you 
should use XtResizeWidget. 

SEE ALSO 

XtMakeGeometryRequest(3X),XtQueryGeometry(3X) 
Programming with Xlib 
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NAME 

XtConvert, XtDirectConvert - invoke resource converters 

SYNTAX 

void XtConvert^, fromjype, from, tojype, to return) 

Widget w; 

String fromjype; 

XrmValuePtr from; 

String tojype; 

XrmValuePtr tojeturn; 
void XtDirectConvert(co«verter, orgs, numjirgs, from, tojeturn) 

XtConverter converter, 

XrmValuePtr orgs; 

Cardinal numjirgs; 

XrmValuePtr from; 

XrmValuePtr tojeturn; 

ARGUMENTS 



orgs 


Specifies the argument list that contains the additional arguments needed to 




perform the conversion (often NULL). 


converter 


Specifies the conversion procedure that is to be called. 


from 


Specifies the value to be converted. 


fromjype 


Specifies the source type. 


num jags 


Specifies the number of additional arguments (often zero). 


tojype 


Specifies the destination type. 


tojeturn 


Returns the converted value. 


w 


Specifies the widget to use for additional arguments (if any are needed). 



DESCRIPTION 

The XtConvert function looks up the type converter registered to convert from_type to to_type, 
computes any additional arguments needed, and then calls XtDirectConvert. The 
XtDirectConvert function looks in the converter cache to see if this conversion procedure has 
been called with the specified arguments. If so, it returns a descriptor for information stored in 
the cache; otherwise, it calls the converter and enters the result in the cache. Before calling the 
specified converter, XtDirectConvert sets the return value size to zero and the return value 
address to NULL. To determine if the conversion was successful, the client should check 
toreturn.address for non-NULL. 

SEE ALSO 

XtAppAddConverter(3X), XtStringConversionWarning(3X) 
Programming with Xlib 
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NAME 

XtCreateApplicationContext, XtDestroyApplicationContext, XtWidgetToApplicationContext, 
XtToolkitlnitialize - create, destroy, and obtain an application context 

SYNTAX 

XtAppContext XtCreateApplicationContext() 
void XtDestroyApplicationCtontext(^/>_c0«tetf) 

XtAppContext app_context; 
XtAppContext XtWidgetToApplicationContext(H') 

Widget w; 
void XtToolkitInitialize() 

ARGUMENTS 

app_context Specifies the application context. 

w Specifies the widget . 

DESCRIPTION 

The XtCreateApplicationContext function returns an application context, which is an opaque type. 
Every application must have at least one application context. The XtDestroyApplicationContext 
function destroys the specified application context as soon as it is safe to do so. If called from with 
an event dispatch (for example, a callback procedure), XtDestroyApplicationContext does not 
destroy the application context until the dispatch is complete. The 

XtWidgetToApplicationContext function returns the application context for the specified widget. 
The semantics of calling XtToolkitlnitialize more than once are undefined. 

SEE ALSO 

XtDisplayInitialize(3X) 
Programming with Xlib 
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NAME 



XtCreatePopupShell 



SYNTAX 



Widget XtCreatePopupShell(«<z/we, widget _class, parent, orgs, num_args) 
String name; 

WidgetClass widget _class\ 
Widget parent; 
ArgList orgs; 
Cardinal num jtrgs; 



DESCRIPTION 

The XtCreatePopupShell function ensures that the specified class is a subclass of Shell and, 
rather than using insert_child to attach the widget to the parent's children list, attaches the shell to 
the parent's pop-ups list directly. A spring-loaded pop-up invoked from a translation table already 
must exist at the time that the translation is invoked, so the translation manager can find the shell 
by name. Pop-ups invoked in other ways can be created "on-the-fly" when the pop-up actually is 
needed. This delayed creation of the shell is particularly useful when you pop up an unspecified 
number of pop-ups. You can look to see if an appropriate unused shell (that is, not currently 
popped up) exists and create a new shell if needed. 

SEE ALSO 

XtCreateWidget(3X), XtPopdown(3X), XtPopup(3X) 
Programming with Xlib 



ARGUMENTS 
orgs 



Specifies 
Specifies 
Specifies 
Specifies 
Specifies 



the argument list to override the resource defaults, 
the text name for the created shell widget, 
the number of arguments in the argument list, 
the parent widget. 

the widget class pointer for the created shell widget. 



name 



numjags 

parent 

widget_class 
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NAME 

XtCreateWidget, XtCreateManagedWidget, XtDestroyWidget - create and destroy widgets 

SYNTAX 

Widget XtCreateWidget(«ame, widget _class, parent, orgs, numargs) 
String name; 

WidgetClass widget _class; 
Widget parent; 
ArgList orgs; 
Cardinal num args; 
Widget XtCreateManagedWidget(na/we, widget _class, parent, orgs, numjtrgs) 
String name; 

WidgetClass widget_class; 
Widget parent; 
ArgList orgs; 
Cardinal num jags; 
void XtDestroyWidget(n>) 
Widget w; 

ARGUMENTS 

orgs Specifies the argument list to override the resource defaults. 

name Specifies the resource name for the created widget, which is used for 

retrieving resources and, for that reason, should not be the same as any 
other widget that is a child of same parent. 

numjargs Specifies the number of arguments in the argument list. 

parent Specifies the parent widget. 

w Specifies the widget. 

widget _class Specifies the widget class pointer for the created widget. 

DESCRIPTION 

The XtCreateWidget function performs much of the boilerplate operations of widget creation: 

• Checks to see if the class_initialize procedure has been called for this class and for all 
superclasses and, if not, calls those necessary in a superclass-to-subclass order. 

• Allocates memory for the widget instance. 

• If the parent is a subclass of constraint WidgetClass, it allocates memory for the parent's 
constraints and stores the address of this memory into the constraints field. 

• Initializes the core nonresource data fields (for example, parent and visible). 

• Initializes the resource fields (for example, background_pixel) by using the resource lists 
specified for this class and all superclasses. 

• If the parent is a subclass of constraint WidgetClass, it initializes the resource fields of the 
constraints record by using the constraint resource list specified for the parent's class and all 
superclasses up to constraint WidgetClass. 

• Calls the initialize procedures for the widget by starting at the Core initialize procedure on 
down to the widget's initialize procedure. 

• If the parent is a subclass of compositeWidgetClass, it puts the widget into its parent's 
children list by calling its parent's insert_child procedure. For further information, see 
Section 35. 

• If the parent is a subclass of constraint WidgetClass, it calls the constraint initialize 
procedures, starting at constraintWidgetClass on down to the parent's constraint initialize 
procedure. Note that you can determine the number of arguments in an argument list by 
using the XtNumber macro. For further information, see Section 11.1. The 
XtCreateManagedWidget function is a convenience routine that calls XtCreateWidget and 
XtManageChild. The XtDestroyWidget function provides the only method of destroying a 
widget, including widgets that need to destroy themselves. It can be called at any time, 
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including from an application callback routine of the widget being destroyed. This requires 
a two-phase destroy process in order to avoid dangling references to destroyed widgets. In 
phase one, XtDestroyWidget performs the following: 

• If the being_destroyed field of the widget is True, it returns immediately. 

• Recursively descends the widget tree and sets the being_destroyed field to True for the 
widget and all children. 

• Adds the widget to a list of widgets (the destroy list) that should be destroyed when it is safe 
to do so. Entries on the destroy list satisfy the invariant that if w2 occurs after wl on the 
destroy list then w2 is not a descendent of wl. (A descendant refers to both normal and 
pop-up children.) Phase two occurs when all procedures that should execute as a result of 
the current event have been called (including all procedures registered with the event and 
translation managers), that is, when the current invocation of XtDispatchEvent is about to 
return or immediately if not in XtDispatchEvent. In phase two, XtDestroyWidget performs 
the following on each entry in the destroy list: 

• Calls the destroy callback procedures registered on the widget (and all descendants) in 
post-order (it calls children callbacks before parent callbacks). 

• If the widget's parent is a subclass of compositeWidgetClass and if the parent is not being 
destroyed, it calls XtUnmanageChild on the widget and then calls the widget's parent's 
delete_child procedure (see Section 3.4). 

• If the widget's parent is a subclass of constraint WidgetClass, it calls the constraint destroy 
procedure for the parent, then the parent's superclass, until finally it calls the constraint 
destroy procedure for constraint WidgetClass. 

• Calls the destroy methods for the widget (and all descendants) in post-order. For each such 
widget, it calls the destroy procedure declared in the widget class, then the destroy 
procedure declared in its superclass, until finally it calls the destroy procedure declared in 
the Core class record. 

• Calls XDestroyWindow if the widget is realized (that is, has an X window). The server 
recursively destroys all descendant windows. 

• Recursively descends the tree and deallocates all pop-up widgets, constraint records, 
callback lists and, if the widget is a subclass of compositeWidgetClass, children. 

SEE ALSO 

XtAppCreateShell(3X), XtCreatePopupShell(3X) 
Programming with Xlib 
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NAME 



XtCreateWindow - window creation convenience function 



SYNTAX 



void XtCreateWindow(M>, window _class, visual, value jnask, attributes) 
Widget w; 

unsigned int window _class; 
Visual 'visual; 
XtValueMask value mask; 
XSetWindowAttributes 'attributes; 



ARGUMENTS 

attributes 



value jnask 

visual 

w 

window class 



Specifies the window attributes to use in the XCreateWindow call. 

Specifies which attribute fields to use. 

Specifies the visual type (usually CopyFromParent). 

Specifies the widget that is used to set the x,y coordinates and so on. 

Specifies the Xlib window class (for example, InputOutput, InputOnly, or 
CopyFromParent). 

DESCRIPTION 

The XtCreateWindow function calls the Xlib XCreateWindow function with values from the 
widget structure and the passed parameters. Then, it assigns the created window to the widget's 
window field. XtCreateWindow evaluates the following fields of the Core widget structure: 

depth 

screen 

parent -> core.window 
x 

y 

width 
height 

border_width 

SEE ALSO 

Programming with Xlib 
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NAME 

XtDisplay, XtParent, XtScreen, XtWindow - obtain window information about a widget 

SYNTAX 

Display *XtDisplay(H') 

Widget w; 
Widget XtParent(w) 

Widget w; 
Screen 'XtScreen(H') 

Widget m>; 
Window XtWindow(»v) 

Widget w; 

ARGUMENTS 

w Specifies the widget. 

DESCRIPTION 

XtDisplay returns the display pointer for the specified widget. XtParent returns the parent widget 
for the specified widget. XtScreen returns the screen pointer for the specified widget. XtWindow 
returns the window of the specified widget. 

SEE ALSO 

XtClass(3X) 
Programming with Xlib 
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NAME 

XtDispIaylnitialize - a function that initializes the toolkit's view of a display and adds it to an 
application context. 

SYNTAX 

• include <Xm/Xm.h> 

Widget XtDispIaylnitialize (app ^context, display, application juane, application _class, options, 
num_options, argc, argy) 

XtAppContext app_context; 

Display * display; 

String application jtame; 

String application jclass; 

XrmOptionDescRec options; 

Cardinal num_options; 

Cardinal * argc; 

String argv, 

DESCRIPTION 

XtDispIaylnitialize parses the command line that invoked the application, and loads the resource 
database. XtDispIaylnitialize is a back-end routine that is usually called be Xtlnitialize. It may be 
called directly if the application needs to open more than one display. XtDipIaylnitialize is passed 
an open display. XtOpenDisplay can be used in the case where an open display has not yet been 
generated. 

Bypassing the command line that invoked your application to XtDispIaylnitialize, the function 
can parse the line to allow users to specify certain resources (such as fonts and colors) for your 
application at run time. XtDispIaylnitialize scans the command line and removes those options. 
The rest of your application sees only the remaining options. 

XtDispIaylnitialize supports localization of defaults files based on the value of the LANG 
environment variable. The user can specify a language by using the LANG environment variable. 
Elements of this variable are then used to establish a path to the proper resource files. The 
following substitutions are used in building the path: 

• %N is replaced by class_name of the application. 

• %L is replaced by the value of LANG environment variable. 

• %l is replaced by the language part of LANG environment variable. 

• %t is replaced by the territory part of LANG environment variable. 

• %c is replaced by the code set part of LANG environment variable. 

• %% is replaced by %. 

If the LANG environment variable is not defined, or if one of its parts is missing, then a % 
element that references it is replaced by NULL. 

The paths contain a series of elements separated by colons. Each element denotes a file name, 
and the file names are looked up left to right till one of them succeeds. Before doing the lookup, 
substitutions are performed. 

NOTE: We are using the X/Open convention of collapsing multiple adjoining slashes in a 
filename into one slash. 

The Xtlnitalize function loads the resource database by merging in resources from these sources: 

• Application-specific class resource file on the local host. 

• Application-specific user resource file on the local host. 

• Resource property on the server or user preference resource file on the local host. 

• Per-host user environment resource file on the local host. 
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• The application command line (argv). 

To load the application-specific class resource file, XtDisplaylnitialize performs the appropriate 
substitutions on this path: 

• /usr/lib/Xll/%L/app-defaults/%N:/usr/lib/Xll/app-defaults/%N 

If LANG environment variable is not defined (or the first path lookup using LANG fails), then the 
lookup will default to the current non-language specific location 
(/usr/lib/Xll/app_defaults/%N). 

To load the user's application resource file, XtDisplaylnitialize performs the following steps: 

• Use XAPPLRESLANGPATH environment variable to look up the file. A possible value for 
XAPPLRESLANGDIR is: 

7%N:$HOME/app-defaults/%L/%N:$HOME/app-defaults/%N:$HOME/%L/%N:$HOME/%N 

• If that fails, or if XAPPLPRESLANGPATH is not defined, and if XAPPLRESDIR is defined, 
use the following as the path: 

$XAPPLRESDIR%L/%N:$XAPPLRESDIR%N 

• else use: 

$HOME/%L/%N:$HOME/%N 

Note that if the XAPPLRESLANGPATH lookup is not successful and LANG is not defined the 
lookup is then equivalent to that used by the R3 specification of Xtlnitialize (actually described 
under XtDisplaylnitialize). 

The parameters for XtDisplaylnitialize are defined below: 
app_context Specifies the application context. 

display Specifies the display. Note that a display can be in at most one 

application context. 

application jiame Specifies the name of this application. 

application _class Specifies the class name of this application, which usually is the generic 

name for all instances of this application. By convention, the class name 
is formed by reversing the case of the application's first letter. The class 
name is used to locate the files used to initialize the resource database. 

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to 
XrmParseCommand. 

numjyptions Specifies the number of entries in options list 

argc Specifies a pointer to the number of command line parameters. 

at$y Specifies the command line parameters. 



SEE ALSO 

XtInitialize(3X) 
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NAME 



XtGetGC, XtReleaseGC - obtain and destroy a sharable GC 



SYNTAX 



GC XtGetGC(»v, value jnask, values) 
Widget w; 

XtGCMask value jnask; 
XGCValues 'values; 
void XtReleaseGC(n>, gc) 
Widget w; 
GC gc; 



DESCRIPTION 

The XtGetGC function returns a sharable, read-only GC. The parameters to this function are the 
same as those for XCreateGC except that a widget is passed instead of a display. XtGetGC shares 
only GCs in which all values in the GC returned by XCreateGC are the same. In particular, it 
does not use the value_mask provided to determine which fields of the GC a widget considers 
relevant. The value_mask is used only to tell the server which fields should be filled in with 
widget data and which it should fill in with default values. For further information about 
valuemask and values, see XCreateGC in the Programming with Xlib . The XtReleaseGC 
function deallocate the specified shared GC. 

SEE ALSO 

Programming with Xlib 
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ARGUMENTS 
& 

values 



Specifies the GC to be deallocated. 
Specifies the actual values for this GC. 
Specifies which fields of the values are specified. 
Specifies the widget. 



value mask 
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NAME 

XtGetResourceList - obtain resource list 

SYNTAX 

void XtGetResourceList(c/as5, resources jeturn, num resources return); 
WidgetClass class; 
^ kesourceList Resources return; 
Cardinal *num resources return; 

ARGUMENTS 

num jesources jeturn 

Specifies a pointer to where to store the number of entries in the resource 
list. 

resources jeturn Specifies a pointer to where to store the returned resource list. The caller 
must free this storage using XtFree when done with it. 

widget jlass Specifies the widget class. 

DESCRIPTION 

If it is called before the widget class is initialized (that is, before the first widget of that class has 
been created), XtGetResourceList returns the resource list as specified in the widget class record. 
If it is called after the widget class has been initialized, XtGetResourceList returns a merged 
resource list that contains the resources for all superclasses. 

SEE ALSO 

XtGetSubresources(3X), XtOffset(3X) 
Programming with Xlib 
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NAME 

XtParseTranslationTable, XtAugmentTranslations, XtOverrideTranslations, 
XtUninstallTranslations - manage translation tables 

SYNTAX 

XtTranslations XtParseTranslationTable(taWe) 

String table; 
void XtAugmentTranslations(»v, translations) 

Widget w; 

XtTranslations translations; 
void XtOverrideTranslations^, translations') 
Widget w; 

XtTranslations translations; 
void XtUninstallTranslations(H>) 
Widget w; 

ARGUMENTS 

table Specifies the translation table to compile. 

translations Specifies the compiled translation table to merge in (must not be NULL). 

w Specifies the widget into which the new translations are to be merged or 

removed. 

DESCRIPTION 

The XtParseTranslationTable function compiles the translation table into the opaque internal 
representation of type XtTranslations. Note that if an empty translation table is required for any 
purpose, one can be obtained by calling XtParseTranslationTable and passing an empty string. 
The XtAugmentTranslations function nondestructively merges the new translations into the 
existing widget translations. If the new translations contain an event or event sequence that 
already exists in the widget's translations, the new translation is ignored. The 
XtOverrideTranslations function destructively merges the new translations into the existing widget 
translations. If the new translations contain an event or event sequence that already exists in the 
widget's translations, the new translation is merged in and override the widget's translation. To 
replace a widget's translations completely, use XtSetValues on the XtNtranslations resource and 
specifiy a compiled translation table as the value. The XtUninstallTranslations function causes 
the entire translation table for widget to be removed. 

SEE ALSO 

XtAppAddActions(3X), XtCreatePopupShell(3X), XtParseAcceleratorTable(3X), XtPopup(3X) 
Programming with Xlib 
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NAME 

XtPopdown, XtCallbackPopdown, MenuPopdown - unmap a pop-up 

SYNTAX 

void XtPop6ovm(popup_sheU) 

Widget popup jhell\ 
void XtCallbackPopdown(M>, client _data, calljlata) 

Widget w; 

caddr_t client _data; 

caddr_t calljlata; 
void MenuPopd"own(s/»e//_«ame) 

String shell jtame; 

ARGUMENTS 

calljlata 

client jlata 

popup jhell 

shelljtame 

w 

DESCRIPTION 

The XtPopdown function performs the following: 

• Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

• Checks that popup_shell is currently popped_up; otherwise, it generates an error. 

• Unmaps popup_shell's window. 

• If popup_shell's grab_kind is either XtGrabNonexclusive or XtGrabExclusive, it calls 
XtRemoveGrab. 

• Sets pop-up shell's popped_up field to False. 

• Calls the callback procedures on the shell's popdown_callback list. The 
XtCallbackPopdown function casts the client data parameter to an XtPopdownID pointer: 
typedef struct { 

Widget shell_widget; 

Widget enable_widget; 
} XtPopdownlDRec, "XtPopdownID; 
The shell_widget is the pop-up shell to pop down, and the enable_widget is the widget that was used to 
pop it up. XtCallbackPopdown calls XtPopdown with the specified shell_widget and then calls 
XtSetSensitive to resensitize the enable_widget. If a shell name is not given, MenuPopdown calls 
XtPopdown with the widget for which the translation is specified. If a shell_name is specified in the 
translation table, MenuPopdown tries to find the shell by looking up the widget tree starting at the parent 
of the widget in which it is invoked. If it finds a shell with the specified name in the pop-up children of 
that parent, it pops down the shell; otherwise, it moves up the parent chain as needed. If MenuPopdown 
gets to the application top-level shell widget and cannot find a matching shell, it generates an error. 

SEE ALSO 

XtCreatePopupShell(3X),XtPopup(3X) 
Programming with Xlib 



Specifies the callback data, which is not used by this procedure. 
Specifies a pointer to the XtPopdownID structure. 
Specifies the widget shell to pop down. 
Specifies the name of the widget shell to pop down. 
Specifies the widget. 
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NAME 

XtPopup, XtCallbackNone, XtCallbackNonexclusive, XtCallbackExclusive, MenuPopup - map a 
pop-up 

SYNTAX 

void Xt¥opup(popup_shell, grabjdnd) 

Widget popup _shell; 

XtGrabKind grabjdnd; 
void XtCallbackNone(n>, client jiata, call_data) 

Widget w; 

caddr_t client jiata; 

caddr_t calljlata; 
void XtCallbackNonexclusive^, client data, calljlata) 

Widget h>; 

caddr_t client _data; 

caddr_t calljlata; 
void XtCallbackExclusive(H', client jiata, calljlata) 

Widget w; 

caddr_t client jiata; 

caddr_t calljlata; 
void MenuPopup(s/je//_«ame) 

String shell jtame; 

ARGUMENTS 

calljlata Specifies the callback data, which is not used by this procedure. 

client jiata Specifies the pop-up shell. 

grabjdnd Specifies the way in which user events should be constrained. 

popup jhell Specifies the widget shell. 

w Specifies the widget. 

DESCRIPTION 

The XtPopup function performs the following: 

• Calls XtCheckSubclass to ensure popup_shell is a subclass of Shell. 

• Generates an error if the shell's popped_up field is already True. 

• Calls the callback procedures on the shell's popup_callback list. 

• Sets the shell popped_up field to True, the shell spring_loaded field to False, and the shell 
grab_kind field from grab_kind. 

• If the shell's create_popup_child field is non-NULL, XtPopup calls it with popupjshell as 
the parameter. 

• If grab_kind is either XtGrabNonexcIusive or XtGrabExcIusive, it calls: 
XtAddGrab(popup_shell, (grab_kind = = XtGrabExcIusive), False) 

• Calls XtRealizeWidget with popup_shell specified. 

• Calls XMapWindow with popup_shell specified. The XtCallbackNone, 
XtCallbackNonexclusive, and XtCallbackExclusive functions call XtPopup with the shell 
specified by the client data argument and grab_kind set as the name specifies. 
XtCallbackNone, XtCallbackNonexclusive, and XtCallbackExclusive specify XtGrabNone, 
XtGrabNonexcIusive, and XtGrabExcIusive, respectively. Each function then sets the 
widget that executed the callback list to be insensitive by using XtSetSensitive. Using these 
functions in callbacks is not required. In particular, an application must provide customized 
code for callbacks that create pop-up shells dynamically or that must do more than 
desensitizing the button. MenuPopup is known to the translation manager, which must 
perform special actions for spring-loaded pop-ups. Calls to MenuPopup in a translation 
specification are mapped into calls to a nonexported action procedure, and the translation 
manager fills in parameters based on the event specified on the left-hand side of a 
translation. If MenuPopup is invoked on ButtonPress (possibly with modifiers), the 
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translation manager pops up the shell with grab_kind set to XtGrabExclusive and 
spring loaded set to True. If MenuPopup is invoked on EnterWindow (possibly with 
modifiers), the translation manager pops up the shell with grab_kind set to 
XtGrabNonexclusive and spring_loaded set to False. Otherwise, the translation manager 
generates an error. When the widget is popped up, the following actions occur: 

• Calls XtCheckSubclass to ensure popup shell is a subclass of Shell. 

• Generates an error if the shell's popped_up field is already True. 

• Calls the callback procedures on the shell's popup_callback list. 

• Sets the shell popped_up field to True and the shell grab_kind and spring_loaded fields 
appropriately. 

• If the shell's create _popup_child field is non-NULL, it is called with popup_shell as the 
parameter. 

• Calls: 

XtAddGrab(popup_shell, (grabjcind = = XtGrabExclusive), springjoaded) 

• Calls XtRealizeWidget with popup_shell specified. 

• Calls XMapWindow with popup shell specified. (Note that these actions are the same as 
those for XtPopup.) MenuPopup tries to find the shell by searching the widget tree starting 
at the parent of the widget in which it is invoked. If it finds a shell with the specified name 
in the pop-up children of that parent, it pops up the shell with the appropriate parameters. 
Otherwise, it moves up the parent chain as needed. If MenuPopup gets to the application 
widget and cannot find a matching shell, it generates an error. 

SEE ALSO 

XtCreatePopupShell(3X),XtPopdown(3X) 
Programming with Xlib 
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NAME 

XtQueryGeometry - query the preferred geometry of a child widget 

SYNTAX 

XtGeometryResult XtQueryGeometryOv, intended, preferred [return) 
Widget w; 

XtWidgetGeometry *intended, *pref erred return; 
ARGUMENTS 

intended Specifies any changes the parent plans to make to the child's geometry or 

NULL. 

preferred return Returns the child widget's preferred geometry. 
w Specifies the widget. 

DESCRIPTION 

To discover a child's preferred geometry, the child's parent sets any changes that it intends to 
make to the child's geometry in the corresponding fields of the intended structure, sets the 
corresponding bits in intended.request_mode, and calls XtQueryGeometry. XtQueryGeometry 
clears all bits in the preferred_return->request_mode and checks the query_geometry field of the 
specified widget's class record. If query_geometry is not NULL, XtQueryGeometry calls the 
query_geometry procedure and passes as arguments the specified widget, intended, and 
preferred_return structures. If the intended argument is NULL, XtQueryGeometry replaces it 
with a pointer to an XtWidgetGeometry structure with requestmode =0 before calling 
query_geometry. 

SEE ALSO 

XtConfigureWidget(3X), XtMakeGeometryRequest(3X) 
Programming with Xlib 
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NAME 

XtRealizeWidget, XtlsRealized, XtUnrealizeWidget - realize and unrealize widgets 

SYNTAX 

void XtRealizeWidget(H>) 

Widget w; 
Boolean XtIsRealized(M>) 

Widget w; 
void XtUnrealizeWidget(H') 

Widget h>; 

ARGUMENTS 

w Specifies the widget. 

DESCRIPTION 

If the widget is already realized, XtRealizeWidget simply returns. Otherwise, it performs the 
following: 

• Binds all action names in the widget's translation table to procedures (see Section 10.1.2). 

• Makes a post-order traversal of the widget tree rooted at the specified widget and calls the 
change_managed procedure of each composite widget that has one or more managed 
children. 

• Constructs an XSetWindowAttributes structure filled in with information derived from the 
Core widget fields and calls the realize procedure for the widget, which adds any widget- 
specific attributes and creates the X window. 

• If the widget is not a subclass of compositeWidgetClass, XtRealizeWidget returns; 
otherwise, it continues and performs the following: 

Descends recursively to each of the widget's managed children and calls the realize 
procedures. Primitive widgets that instantiate children are responsible for realizing 
those children themselves. 

Maps all of the managed children windows that have mapped_when_managed True. 
(If a widget is managed but mapped_when_managed is False, the widget is allocated 
visual space but is not displayed. Some people seem to like this to indicate certain 
states.) 

If the widget is a top-level shell widget (that is, it has no parent), and mapped_when_managed is 
True, XtRealizeWidget maps the widget window. The XtlsRealized function returns True if the 
widget has been realized, that is, if the widget has a nonzero X window ID. Some widget 
procedures (for example, set_values) might wish to operate differently after the widget has been 
realized. The XtUnrealizeWidget function destroys the windows of an existing widget and all of its 
children (recursively down the widget tree). To recreate the windows at a later time, call 
XtRealizeWidget again. If the widget was managed, it will be unmanaged automatically before its 
window is freed. 

SEE ALSO 

XtManageChildren(3X) 
Programming with Xlib 
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NAME 

XtSetArg, XtMergeArgLists - set and merge ArgLists 

SYNTAX 

XtSetArg(o?g, name, value) 

Atgarg, 

String name; 

XtArgVal value; 
ArgList XtMergeArgLists(a/gs7, num_argsl, args2, num_args2) 

ArgList argsl; 

Cardinal num argsl; 

ArgList argsl; 

Cardinal num_args2; 

ARGUMENTS 



org 


Specifies the name-value pair to set. 


argsl 


Specifies the first ArgList. 


orgs? 


Specifies the second ArgList. 


numjtrgsl 


Specifies the number of arguments in the first argument list. 


num_args2 


Specifies the number of arguments in the second argument list. 


name 


Specifies the name of the resource. 


value 


Specifies the value of the resource if it will fit in an XtArgVal or the address. 



DESCRIPTION 

The XtSetArg function is usually used in a highly stylized manner to minimize the probability of 
making a mistake; for example: 
Arg args[20]; 
int n; 

n = 0; 

XtSetArg(args[n], XtNheight, 100); n+ + ; 

XtSetArg(args[n], XtNwidth, 200); n+ + ; 

XtSetValues(widget, args, n); 
Alternatively, an application can statically declare the argument list and use XtNumber: 
static Args argsQ = { 

{XtNheight, (XtArgVal) 100}, 
{XtNwidth, (XtArgVal) 200}, 

}; 

XtSetValues(Widget, args, XtNumber(args)); 

Note that you should not use auto-increment or auto-decrement within the first argument to XtSetArg. 
XtSetArg can be implemented as a macro that dereferences the first argument twice. The 
XtMergeArgLists function allocates enough storage to hold the combined ArgList structures and copies 
them into it Note that it does not check for duplicate entries. When it is no longer needed, free the 
returned storage by using XtFree. 

SEE ALSO 

XtOffset(3X) 
Programming with Xlib 
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NAME 



XtSetKeyboardFocus - focus events on a child widget 



SYNTAX 



XtSetKeyboardFocus(swZ><ree, descendant) 
Widget subtree, descendant; 



ARGUMENTS 



descendant 



w 



Specifies either the widget in the subtree structure which is to receive the 
keyboard event, or None. Note that it is not an error to specify None when 
no input focus was previously set. 

Specifies the widget for which the keyboard focus is to be set. 



DESCRIPTION 



If a future KeyPress or KeyRelease event occurs within the specified subtree, 
XtSetKeyboardFocus causes XtDispatchEvent to remap and send the event to the specified 
descendant widget When there is no modal cascade, keyboard events can occur within a widget 
W in one of three ways: 

• W has the X input focus. 

• W has the keyboard focus of one of its ancestors, and the event occurs within the ancestor or 
one of the ancestor's descendants. 

• No ancestor of W has a descendant within the keyboard focus, and the pointer is within W. 
When there is a modal cascade, a widget W receives keyboard events if an ancestor of W is 
in the active subset of the modal cascade and one or more of the previous conditions is 
True. When subtree or one of its descendants acquires the X input focus or the pointer 
moves into the subtree such that keyboard events would now be delivered to subtree, a 
Focusln event is generated for the descendant if FocusNotify events have been selected by 
the descendant. Similarly, when W loses the X input focus or the keyboard focus for one of 
its ancestors, a FocusOut event is generated for descendant if FocusNotify events have been 
selected by the descendant. 



SEE ALSO 



XtCallAcceptFocus(3X) 
Programming with Xlib 
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NAME 

XtSetKeyTranslator, XtTranslateKeycode, XtRegisterCaseConverter, XtConvertCase - convert 
KeySym to KeyCodes 

SYNTAX 

void XtSetKeyTranslator(rfi$p/ay, proc) 
Display * display; 
XtKeyProc proc; 

void XtTranslateKeycode(rft$p/ay, keycode, modifiers, modifiers return , keysym jeturn) 

Display "display; 

KeyCode keycode; 

Modifiers modifiers; 

Modifiers "modifiers jeturn; 

KeySym "keysym jetum; 
void XtRegisterCaseCbnverter(tfisp/ay, proc, start, stop) 

Display * display; 

XtCaseProc proc; 

KeySym start, 

KeySym stop; 

void XtConvertCase(rfi$p/ay, keysym, lower return, upper return) 
Display "display; 
KeySym keysym; 
KeySym "lower jeturn; 
KeySym "upper jeturn; 

ARGUMENTS 



display 


Specifies the display. 


keycode 


Specifies the KeyCode to translate. 


keysym 


Specifies the KeySym to convert. 


keysym jeturn 


Returns the resulting KeySym. 


lower jeturn 


Returns the lowercase equivalent of the KeySym. 


upper jeturn 


Returns the uppercase equivalent of the KeySym. 


modifiers 


Specifies the modifiers to the KeyCode. 


modifiers return 


Returns a mask that indicates the modifiers actually used to generate the 




KeySym. 


proc 


Specifies the procedure that is to perform key translations or conversions. 


start 


Specifies the first KeySym for which this converter is valid. 


stop 


Specifies the last KeySym for which this converter is valid. 



DESCRIPTION 

The XtSetKeyTranslator function sets the specified procedure as the current key translator. The 
default translator is XtTranslateKey, an XtKeyProc that uses Shift and Lock modifiers with the 
interpretations defined by the core protocol. It is provided so that new translators can call it to get 
default KeyCode-to-KeySym translations and so that the default translator can be reinstalled. The 
XtTranslateKeycode function passes the specified arguments directly to the currently registered 
KeyCode to KeySym translator. The XtRegisterCaseConverter registers the specified case 
converter. The start and stop arguments provide the inclusive range of KeySyms for which this 
converter is to be called. The new converter overrides any previous converters for KeySyms in 
that range. No interface exists to remove converters; you need to register an identity converter. 
When a new converter is registered, the X Toolkit Intrinsics refreshes the keyboard state if 
necessary. The default converter understands case conversion for all KeySyms defined in the core 
protocol. The XtConvertCase function calls the appropriate converter and returns the results. A 
user-supplied XtKeyProc may need to use this function. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtSetSensitive, XtlsSensitive - set and check a widget's sensitivity state 

SYNTAX 

void XtSetSensitive^, sensitive') 

Widget w; 

Boolean sensitive; 
Boolean XtIsSensitive(M>) 

Widget w; 

ARGUMENTS 

sensitive Specifies a Boolean value that indicates whether the widget should receive 

keyboard and pointer events. 

w Specifies the widget. 

DESCRIPTION 

The XtSetSensitive function first calls XtSetValues on the current widget with an argument list 
specifying that the sensitive field should change to the new value. It then recursively propagates 
the new value down the managed children tree by calling XtSetValues on each child to set the 
ancestorjsensitive to the new value if the new values for sensitive and the child's ancestor_sensitive 
are not the same. XtSetSensitive calls XtSetValues to change sensitive and ancestorjsensitive. 
Therefore, when one of these changes, the widget's set_values procedure should take whatever 
display actions are needed (for example, greying out or stippling the widget). XtSetSensitive 
maintains the invariant that if parent has either sensitive or ancestorjsensitive False, then all 
children have ancestorjsensitive False. The XtlsSensitive function returns True or False to 
indicate whether or not user input events are being dispatched. If both corcsensitive and 
core.ancestorjsensitive are True, XtlsSensitive returns True; otherwise, it returns False. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtSetValues, XtSetSubvalues, XtGetValues, XtGetSubvalues - obtain and set widget resources 

SYNTAX 

void XtSetValues(H>, orgs, num_args) 

Widget w; 

ArgList orgs; 

Cardinal num_args; 
void XtSetSubvalues(6ase, resources, num resources, orgs, num_args) 

caddr_t base; 

XtResourceList resources; 

Cardinal num resources; 

ArgList orgs; 

Cardinal numjtrgs; 
void XtGetValues(M>, orgs, numjtrgs) 

Widget w; 

ArgList orgs; 

Cardinal num jags; 
void XtGetSubvalues(6ase, resources, numjesources, orgs, numjtrgs) 

caddr_t base; 

XtResourceList resources; 

Cardinal numjesources; 

ArgList orgs; 

Cardinal num jags; 

ARGUMENTS 

orgs Specifies the argument list of name/address pairs that contain the resource 

name and either the address into which the resource value is to be stored or 
their new values. 

base Specifies the base address of the subpart data structure where the resources 

should be retrieved or written. 

numjtrgs Specifies the number of arguments in the argument list. 

resources Specifies the nonwidget resource list or values. 

numjesources Specifies the number of resources in the resource list. 

w Specifies the widget. 

DESCRIPTION 

The XtSetValues function starts with the resources specified for the Core widget fields and 
proceeds down the subclass chain to the widget. At each stage, it writes the new value (if specified 
by one of the arguments) or the existing value (if no new value is specified) to a new widget data 
record. XtSetValues then calls the set_values procedures for the widget in superclass-to-subclass 
order. If the widget has any non-NULL set_values_hook fields, these are called immediately after 
the corresponding set_values procedure. This procedure permits subclasses to set nonwidget data 
for XtSetValues. If the widget's parent is a subclass of constraint WidgetClass, XtSetValues also 
updates the widget's constraints. It starts with the constraint resources specified for 
constraintWidgetClass and proceeds down the subclass chain to the parent's class. At each stage, 
it writes the new value or the existing value to a new constraint record. It then calls the constraint 
set_values procedures from constraintWidgetClass down to the parent's class. The constraint 
setvalues procedures are called with widget arguments, as for all set_values procedures, not just 
the constraint record arguments, so that they can make adjustments to the desired values based on 
full information about the widget. XtSetValues determines if a geometry request is needed by 
comparing the current widget to the new widget. If any geometry changes are required, it makes 
the request, and the geometry manager returns XtGeometryYes, XtGeometryAlmost, or 
XtGeometryNo. If XtGeometryYes, XtSetValues calls the widget's resize procedure. If 
XtGeometryNo, XtSetValues resets the geometry fields to their original values. If 
XtGeometryAlmost, XtSetValues calls the set_values_almost procedure, which determines what 
should be done and writes new values for the geometry fields into the new widget. XtSetValues 
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then repeats this process, deciding once more whether the geometry manager should be called. 
Finally, if any of the set_values procedures returned True, XtSetValues causes the widget's expose 
procedure to be invoked by calling the Xlib XClearArea function on the widget's window. The 
XtSetSubvalues function stores resources into the structure identified by base. The XtGetValues 
function starts with the resources specified for the core widget fields and proceeds down the 
subclass chain to the widget. The value field of a passed argument list should contain the address 
into which to store the corresponding resource value. It is the caller's responsibility to allocate 
and deallocate this storage according to the size of the resource representation type used within 
the widget. If the widget's parent is a subclass of constraint WidgetClass, XtGetValues then 
fetches the values for any constraint resources requested. It starts with the constraint resources 
specified for constraintWidgetCIass and proceeds down to the subclass chain to the parent's 
constraint resources. If the argument list contains a resource name that is not found in any of the 
resource lists searched, the value at the corresponding address is not modified. Finally, if the 
get_values_hook procedures are non-NULL, they are called in superclass-to-subclass order after 
all the resource values have been fetched by XtGetValues. This permits a subclass to provide 
nonwidget resource data to XtGetValues. The XtGetSubvalues function obtains resource values 
from the structure identified by base. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtStringConversionWarning - issue a conversion warning message 

SYNTAX 

void XtStringConversionWarning(5rc, dstjype) 
String src, dstjype; 

ARGUMENTS 

src Specifies the string that could not be converted. 

dstjype Specifies the name of the type to which the string could not be converted. 

DESCRIPTION 

The XtStringConversionWarning function issues a warning message with name 
"conversionError", type "string", class "XtToolkitError, and the default message string "Cannot 
convert "src" to type dstjype". 

SEE ALSO 

XtAppAddConverter(3X), XtAppErrorMsg(3X), XtConvert(3X) 
Programming with Xlib 
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NAME 



XtTranslateCoordinates - translate widget coordinates 



SYNTAX 



void XtTranslateCoords(H>,#, v, rootxjeturn, rooty return) 
Widget w, 
Position 

Position *rootx return, *rootyjeturn; 



ARGUMENTS 



rootxjeturn 
rooty jetum 



Returns the root-relative x and y coordinates. 



x 



y 



w 



Specify the widget-relative x and y coordinates. 
Specifies the widget. 



DESCRIPTION 

While XtTranslateCoords is similar to the Xlib XTranslateCoordinates function, it does not 
generate a server request because all the required information already is in the widget's data 
structures. 

SEE ALSO 

Programming with Xlib 
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NAME 

XtUngrabKey - a function that cancels a passive grab on a key combination. 

SYNTAX 

#include < Xll/PassivGrab.h > 
void XtUngrabKey (widget, keycode, modifiers) 



DESCRIPTION 

XtUngrabKey cancels the passive grab on the key combination on the specified widget and allows 
the client to redirect the specified key event to the root widget of a hierarchy. 



Widget 
Keycode 
unsigned int 



widget; 
keycode; 
modifiers; 



widget 

keycode 

modifiers 



Specifies the root widget to the XtUngrabKey call. 

Specifies the Keycode. This maps to the specific key to be grabbed. 



Specifies the set of keymasks. This mask is the bitwise inclusive OR of these 
keymask bits: ShiftMask, LockMask, ControlMask, ModlMask, Mod2Mask, 
Mod3Mask, Mod4Mask, Mod5Mask. You can also pass AnyModifier, which is 
equivalent to issuing the ungrab key request for all possible modifier 
combinations, including the combination of no modifiers. 



SEE ALSO 



XtGrabKey(3X) 
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NAME 

XtUngrabKeyboard - a function releases an active grab on the keyboard. 

SYNTAX 

#include < Xll/PassivGrab.h > 

void XtUngrabKeyboard (widget, time)) 
Widget widget; 
Time time; 

DESCRIPTION 

XtUngrabKeyboard releases any active grab on the keyboard. 

widget Specifies the root widget to the XtUngrabKeyboard call. 

time Specifies the time. You can pass either a timestamp, expressed in milliseconds, or 

CurrentTime. 

SEE ALSO 

XtGrabKeyboard(3X) 
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NAME 

XtGetSelectionValue, XtGetSelectionValues, XtGetSelectionValuesIncremental - obtain selection 
values 

SYNTAX 

void XtGetSelectionValue(w>, selection, target, callback, client Jata, time) 
Widget w; 
Atom selection; 
Atom target; 

XtSelectionCallbackProc callback; 
caddr_t client Jata; 
Time time; 

void XtGetSelectionValues^, selection, targets, count, callback, client Jiata, time) 
Widget w; 
Atom selection; 
Atom 'targets; 
int count; 

XtSelectionCallbackProc callback; 
caddr_t client Jiata; 
Time time; 

void XtGetSelectionValuesIncremental(K', selection, targets, count, selection fallback, 
cancel callback, client Jala, time) 

Widget h>; 
Atom selection; 
Atom 'targets; 
int count; 

XtSelectionlncrCallbackProc selection callback; 
XtCancelConvertSelectionProc cancel callback; 
caddrt client data; 
Time time; 

ARGUMENTS 

callback Specifies the callback procedure that is to be called when the selection value 

has been obtained. 

cancel Jallback Specifies the callback procedure that is to be called if the connection is lost. 

client Jiata Specifies the argument that is to be passed to the specified procedure when 

it is called. 

client Jata Specifies the client data (one for each target type) that is passed to the 

callback procedure when it is called for that target. 

count Specifies the length of the targets and client data lists. 

selection Specifies the particular selection desired (that is, primary or secondary). 

selection callback Specifies the callback procedure that is to be called to obtain the next 
incremental chunk of data or for each selection value obtained. 

target Specifies the type of the information that is needed about the selection. 

targets Specifies the types of information that is needed about the selection. 

time Specifies the timestamp that indicates when the selection value is desired. 

h> Specifies the widget that is making the request. 

DESCRIPTION 

The XtGetSelectionValue function requests the value of the selection that has been converted to 
the target type. The specified callback will be called some time after XtGetSelectionValue is called; 
in fact, it may be called before or after XtGetSelectionValue returns. The XtGetSelectionValues 
function is similar to XtGetSelectionValue except that it takes a list of target types and a list of 
client data and obtains the current value of the selection converted to each of the targets. The 
effect is as if each target were specified in a separate call to XtGetSelectionValue. The callback is 
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called once with the corresponding client data for each target. XtGetSelectioriYalues does 
guarantee that all the conversions will use the same selection value becaues the ownership of the 
selection cannot change in the middle of the list, as would be when calling XtGetSelectionValue 
repeatedly. The XtGetSelectionValuelncremental function is similar to XtGetSelectionValue 
except that the callback procedure will be called repeatedly each time upon delivery of the next 
segment of the selection value. The end of the selection value is detected when callback is called 
with a value of length zero. If the transfer of the selection is aborted in the middle of a transfer, 
the cancel callback procedure is called so that the requestor can dispose of the partial selection 
value it has collected up until that point. The XtGetSelectioriValuesIncremental function is similar 
to XtGetSelectionValuelncremental except that it takes a list of targets and client_data. 
XtGetSelectionValuesIncremental is equivalent to calling XtGetSelectionValuelncremental 
successively for each target/client data pair. XtGetSelectioriValuesIncremental does guarantee 
that all the conversions will use the same selection value because the ownership of the selection 
cannot change in the middle of the list, as would be possible when calling 
XtGetSelectionValuelncremental repeatedly. 

SEE ALSO 

XtAppGetSelectionTimeout(3X), XtOwnSelection(3X) 
Programming with Xlib 
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NAME 

XtGetSubresources, XtGetApplicationResources - obtain subresources or application resources 

SYNTAX 

void XtGetSubresources^, base, name, class, resources, numjesources, orgs, numjnrgs) 
Widget w; 
caddr_t base; 
String name; 
String class; 

XtResourceList resources; 
Cardinal numjesources; 
ArgList orgs; 
Cardinal num jags; 

void XtGetApplicationResources^, base, resources, num resources, orgs, num jags) 
Widget w; 
caddr_t base; 
XtResourceList resources; 
Cardinal numjesources; 
ArgList orgs; 
Cardinal num jags; 

ARGUMENTS 

orgs Specifies the argument list to override resources obtained from the resource 

database. 

base Specifies the base address of the subpart data structure where the resources 

should be written. 

class Specifies the class of the subpart. 

name Specifies the name of the subpart. 

num jags Specifies the number of arguments in the argument list. 

numjesources Specifies the number of resources in the resource list. 

resources Specifies the resource list for the subpart. 

w Specifies the widget that wants resources for a subpart or that identifies the 

resource database to search. 

DESCRIPTION 

The XtGetSubresources function constructs a name/class list from the application name/class, the 
name/classes of all its ancestors, and the widget itself. Then, it appends to this list the name/class 
pair passed in. The resources are fetched from the argument list, the resource database, or the 
default values in the resource list. Then, they are copied into the subpart record. If args is NULL, 
num_args must be zero. However, if num_args is zero, the argument list is not referenced. The 
XtGetApplicationResources function first uses the passed widget, which is usually an application 
shell, to construct a resource name and class list, Then, it retrieves the resources from the 
argument list, the resource database, or the resource list default values. After adding base to each 
address, XtGetApplicationResources copies the resources into the address given in the resource 
list. If args is NULL, num_args must be zero. However, if num args is zero, the argument list is 
not referenced. The portable way to specify application resources is to declare them as members 
of a structure and pass the address of the structure as the base argument. 

SEE ALSO 

XtGetResourceList(3X) 
Programming with Xlib 
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NAME 

XtGrabKey - a function that establishes a passive grab on the specified keys. 



SYNTAX 

#include <Xm/Xm.h> 

void XtGrabKey (widget, keycode, modifiers, owner _events, pointer jnode, keyboard jnode) 

Widget widget; 

Keycode keycode; 

unsigned int modifiers; 

Boolean owner jvents; 

int pointer jnode; 

int keyboard jnode; 



DESCRIPTION 

XtGrabKey establishes a passive grab on the specified keys, such that when the specified 
key/modifier combination is pressed, the keyboard is grabbed. It also allows the client to redirect 
the specified key event to the root widget of a hierarchy. 



widget 

keycode 
modifiers 



owner jvents 
pointer jnode 
keyboard jnode 



Specifies the root widget to the XtGrabKeyboard call. All key events 
that would have been dispatched to other subwindows will get 
dispatched to it subject to owner jvents. 

Specifies the Keycode. This maps to the specific key to be grabbed. 

Specifies the set of keymasks. This mask is the bitwise inclusive OR of 
these keymask bits: ShiftMask, LockMask, ControlMask, ModlMask, 
Mod2Mask, Mod3Mask, MotMMask, Mod5Mask. You can also pass 
AnyModifier, which is equivalent to issuing the grab key request for all 
possible modifier combinations, including the combination of no 
modifiers. 

Specifies if the pointer events are to be reported normally (True) or 
with respect to the grab window if selected by the event mask (False). 

Specifies further processing of pointer events. You can pass 
GrabModeSync or GrabModeAsync. 

Specifies further processing of keyboard events. You can pass 
GrabModeSync or GrabModeAsync. 



SEE ALSO 

XGrabKey(3X) and XtUngrabKey(3X). 
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NAME 

XtGrabKeyboard - a function that actively grabs control of the main keyboard. 

SYNTAX 

#include < Xll/PassivGrab.h > 

int XtGrabKeyboard (widget, owner jvents, pointer jnode, keyboard jnode, time) 
Widget widget; 
Boolean owner jvents; 
int pointer jnode; 
int keyboard jnode; 
Time time; 

DESCRIPTION 

XtGrabKeyboard actively grabs control of the main keyboard. If the grab is successful, it returns 
the constant GrabSuccess. Further key events are reported to the grab widget. 

widget Specifies the root widget to the XtGrabKeyboard call. All key events 

that would have been dispatched to other subwindows will get 
dispatched to it subject to owner jvents. 

owner jvents Specifies if the pointer events are to be reported normally (True) or 

with respect to the grab window if selected by the event mask (False). 

pointer jnode Specifies further processing of pointer events. You can pass 

GrabModeSync or GrabModeAsync. 

keyboard jnode Specifies further processing of keyboard events. You can pass 

GrabModeSync or GrabModeAsync. 

time Specifies the time. You can pass either a timestamp, expressed in 

milliseconds, or CurrentTime. 

RETURN VALUE 

Returns the constant GrabSuccess. 



SEE ALSO 

XtUngrabKeyboard(3X). 
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NAME 

Xtlnitialize - a function that initializes the toolkit and returns a top-level shell. 

SYNTAX 

#include <Xm/Xm.h> 

Widget Xtlnitialize (shell name, application _class, options, num_options, argc, <wgv) 
String shelljiame; 
String application _class; 

XrmOptionDescRec options; 
Cardinal numjyptions; 
Cardinal * argc; 

String orgy, 

DESCRIPTION 

The Xt Intrinsics must be initialized before making any other calls to Xt Intrinsics functions. 
Xtlnitialize establishes the connection to the display server, parses the command line that invoked 
the application, loads the resource database, and creates a shell widget to serve as the parent of 
your application widget hierarchy. 

Bypassing the command line that invoked your application to Xtlnitialize, the function can parse 
the line to allow users to specify certain resources (such as fonts and colors) for your application 
at run time. Xtlnitialize scans the command line and removes those options. The rest of your 
application sees only the remaining options. 

There is an alternate set of functions that you can use to initialize the Xt Intrinsics that is not as 
convenient as Xtlnitialize; however, it is more flexible because it lets you decide the type of shell 
you want to use. The function XtToolkitlnitialize just initializes the toolkit. It does not open the 
display or create an application shell. You must do this yourself using XtOpenDisplay and 
XtAppCreateShell. 

Xtlnitialize supports localization of defaults files based on the value of the LANG environment 
variable. The user can specify a language by using the LANG environment variable. Elements of 
this variable are then used to establish a path to the proper resource files. The following 
substitutions are used in building the path: 

• %N is replaced by class_name of the application. 

o %L is replaced by the value of LANG environment variable. 

• %l is replaced by the language part of LANG environment variable. 

• %t is replaced by the territory part of LANG environment variable. 

• %c is replaced by the code set part of LANG environment variable. 

• %% is replaced by %. 

If the LANG environment variable is not defined, or if one of its parts is missing, then a % 
element that references it is replaced by NULL. 

The paths contain a series of elements separated by colons. Each element denotes a file name, 
and the file names are looked up left to right till one of them succeeds. Before doing the lookup, 
substitutions are performed. 

NOTE: We are using the X/Open convention of collapsing multiple adjoining slashes in a 
filename into one slash. 

The Xtlnitalize function loads the resource database by merging in resources from these sources: 

• Application-specific class resource file on the local host. 

• Application-specific user resource file on the local host. 

• Resource property on the server or user preference resource file on the local host. 
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• Per-host user environment resource file on the local host. 

• The application command line (argv). 

To load the application-specific class resource file, Xtlnitialize performs the appropriate 
substitutions on this path: 

• /usr/lib/Xll/%L/app-defaults/%N:/usr/lib/Xll/app-defaults/%N 

If LANG environment variable is not defined (or the first path lookup using LANG fails), then the 
lookup will default to the current non-language specific location 
(/usr/lib/Xll/app_defaults/%N). 

To load the user's application resource file, Xtlnitialize performs the following steps: 

• Use XAPPLRESLANGPATH environment variable to look up the file. A possible value for 
XAPPLRESLANGDIR is: 

./%N:$HOME/app-defaults/%L/%N:$HOME/app-defaults/%N:$HOME/%L/%N:$HOME/%N 

• If that fails, or if XAPPLPRESIANGPATH is not defined, and if XAPPLRESDIR is defined, 
use the following as the path: 

$XAPPLRESDIR%L/%N:$XAPPLRESDIR%N 

• else use: 
$HOME/%L/%N:$HOME/%N 

Note that if the XAPPLRESLANGPATH lookup is not successful and LANG is not defined the 
lookup is then equivalent to that used by the R3 specification of Xtlnitialize (actually described 
under XtDisplaylnitialize). 

The parameters for Xtlnitialize are defined below: 

shell jtame Specifies the name of the application shell widget instance, which usually 

is something generic like "main." This name is used by the Xt Intrinsics 
to search for resources that belong specifically to this shell widget. The 
application name is derived from the -name command line argument or 
if that is not present the trailing component of argv[0]. 

application _class Specifies the class name of this application, which usually is the generic 

name for all instances of this application. By convention, the class name 
is formed by reversing the case of the application's first letter. The class 
name is used to locate the files used to initialize the resource database. 

options Specifies how to parse the command line for any application-specific 

resources. The options argument is passed as a parameter to 
XrmParseCommand. 

num_options Specifies the number of entries in options list. 

argc Specifies a pointer to the number of command line parameters. 

argv Specifies the command line parameters. 

RETURN VALUE 

Returns the widget ID of the top-level shell. The class of the shell is 
ApplicationShellWidgetClass. 

SEE ALSO 

XtDisplayInitialize(3X). 
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NAME 

XtMakeGeometryRequest, XtMakeResizeRequest - make geometry manager request 

SYNTAX 

XtGeometryResult XtMakeGeometryRequest(n', request, reply return) 
Widget w; 

XtWidgetGeometry *request; 
XtWidgetGeometry *reply return; 
XtGeometryResult XtMakeResizeRequest(n', width, height, width return, height return) 
Widget w; 

Dimension width, height; 

Dimension *width return, *height return 

ARGUMENTS 

repfyjetum Returns the allowed widget size or may be NULL if the requesting widget is 

not interested in handling XtGeometryAlmost. 

request Specifies the desired widget geometry (size, position, border width, and 

stacking order). 

w Specifies the widget that is making the request. 

width return 

height jeturn Return the allowed widget width and height. 

DESCRIPTION 

Depending on the condition, XtMakeGeometryRequest performs the following: 

• If the widget is unmanaged or the widget's parent is not realized, it makes the changes and 
returns XtGeometryYes. 

• If the parent is not a subclass of compositeWidgetClass or the parent's geometry_manager is 
NULL, it issues an error. 

• If the widget's being_destroyed field is True, it returns XtGeometryNo. 

• If the widget x, y, width, height and border_width fields are all equal to the requested values, 
it returns XtGeometryYes; otherwise, it calls the parent's geometry_manager procedure with 
the given parameters. 

• If the parent's geometry manager returns XtGeometryYes and if XtCWQueryOnly is not set 
in the request mode and if the widget is realized, XtMakeGeometryRequest calls the 
XConfigureWindow Xlib function to reconfigure the widget's window (set its size, location, 
and stacking order as appropriate). 

• If the geometry manager returns XtGeometryDone, the change has been approved and 
actually has been done. In this case, XtMakeGeometryRequest does no configuring and 
returns XtGeometryYes. XtMakeGeometryRequest never returns XtGeometryDone. 
Otherwise, XtMakeGeometryRequest returns the resulting value from the parent's geometry 
manager. Children of primitive widgets are always unmanaged; thus, 
XtMakeGeometryRequest always returns XtGeometryYes when called by a child of a 
primitive widget. The XtMakeResizeRequest function, a simple interface to 
XtMakeGeometryRequest, creates a XtWidgetGeometry structure and specifies that width 
and height should change. The geometry manager is free to modify any of the other window 
attributes (position or stacking order) to satisfy the resize request. If the return value is 
XtGeometryAlmost, widthjreturn and heigh t_return contain a compromise width and 
height. If these are acceptable, the widget should immediately make an 
XtMakeResizeRequest and request that the compromise width and height be applied. If the 
widget is not interested in XtGeometryAlmost replies, it can pass NULL for width_return 
and height_return. 

SEE ALSO 

XtConfigureWidget(3X), XtQueryGeometery(3X) 
Programming with Xlib 
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NAME 

XtMalloc, XtCalloc, XtRealloc, XtFree, XtNew, XtNewString - memory management functions 

SYNTAX 

char *XtMalloc(.«ze); 

Cardinal size; 
char *XtCalloc(/iM/M, size); 

Cardinal num; 

Cardinal size; 
char *XtRealloc(/«r, num); 

char *ptr, 

Cardinal num; 
void XtFree(p*r); 

char *ptr, 
type *XtNew(type); 

type; 

String XtNewString(«ri«g); 
String string; 

ARGUMENTS 



num 


Specifies the number of bytes or array elements. 


ptr 


Specifies a pointer to the old storage or to the block of storage that is to be 




freed. 


size 


Specifies the size of an array element (in bytes) or the number of bytes 




desired. 


string 


Specifies a previously declared string. 


type 


Specifies a previously declared data type. 



DESCRIPTION 

The XtMalloc functions returns a pointer to a block of storage of at least the specified size bytes. 
If there is insufficient memory to allocate the new block, XtMalloc calls XtErrorMsg. The 
XtCalloc function allocates space for the specified number of array elements of the specified size 
and initializes the space to zero. If there is insufficient memory to allocate the new block, 
XtCalloc calls XtErrorMsg. The XtRealloc function changes the size of a block of storage 
(possibly moving it). Then, it copies the old contents (or as much as will fit) into the new block 
and frees the old block. If there is insufficient memory to allocate the new block, XtRealloc calls 
XtErrorMsg. If ptr is NULL, XtRealloc allocates the new storage without copying the old 
contents; that is, it simply calls XtMalloc. The XtFree function returns storage and allows it to be 
reused. If ptr is NULL, XtFree returns immediately. XtNew returns a pointer to the allocated 
storage. If there is insufficient memory to allocate the new block, XtNew calls XtErrorMsg. 
XtNew is a convenience macro that calls XtMalloc with the following arguments specified: 
((type *) XtMalloc((unsigned) sizeof(type)) 
XtNewString returns a pointer to the allocated storage. If there is insufficient memory to allocate the new block, 
XtNewString calls XtErrorMsg. XtNewString is a convenience macro that calls XtMalloc with the following arguments 
specified: 

(strcpy(XtMalloc((unsigned) strlen(str) + 1), str)) 

SEE ALSO 

Programming with Xlib 
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NAME 

XtManageChildren, XtManageChild, XtUnmanageChildren, XtUnmanageChild - manage and 
unmanage children 

SYNTAX 

typedef Widget *WidgetList; 

void XtManageChildren(c/w'Wre», num_children) 

WidgetList children; 

Cardinal num. children; 
void XtManageChlld(cMrf) 

Widget child; 
void XtUnmanageChildren(c/iiWre«, num_children) 

WidgetList children; 

Cardinal nuntjchUdren; 
void XtUnmanageChild(c/«7<i) 

Widget child; 

ARGUMENTS 

child Specifies the child. 

children Specifies a list of child widgets. 

numjchildren Specifies the number of children. 

DESCRIPTION 

The XtManageChildren function performs the following: 

• Issues an error if the children do not all have the same parent or if the parent is not a 
subclass of compositeWidgetClass. 

• Returns immediately if the common parent is being destroyed; otherwise, for each unique 
child on the list, XtManageChildren ignores the child if it already is managed or is being 
destroyed and marks it if not. 

• If the parent is realized and after all children have been marked, it makes some of the newly 
managed children viewable: 

Calls the changejnanaged routine of the widgets' parent. 

Calls XtRealizeWidget on each previously unmanaged child that is unrealized. 

Maps each previously unmanaged child that has map_when_managed True. 
Managing children is independent of the ordering of children and independent of creating and 
deleting children. The layout routine of the parent should consider children whose managed field 
is True and should ignore all other children. Note that some composite widgets, especially fixed 
boxes, call XtManageChild from their insert_child procedure. If the parent widget is realized, its 
changejnanaged procedure is called to notify it that its set of managed children has changed. The 
parent can reposition and resize any of its children. It moves each child as needed by calling 
XtMoveWidget, which first updates the x and y fields and then calls XMoveWindow if the widget 
is realized. The XtManageChild function constructs a WidgetList of length one and calls 
XtManageChildren. The XtUnmanageChildren function performs the following: 

• Issues an error if the children do not all have the same parent or if the parent is not a 
subclass of compositeWidgetClass. 

• Returns immediately if the common parent is being destroyed; otherwise, for each unique 
child on the list, XtUnmanageChildren performs the following: 

Ignores the child if it already is unmanaged or is being destroyed and marks it if not. 

If the child is realized, it makes it nonvisible by unmapping it. 

• Calls the changejnanaged routine of the widgets' parent after all children have been 
marked if the parent is realized. XtUnmanageChildren does not destroy the children 
widgets. Removing widgets from a parent's managed set is often a temporary banishment, 
and, some time later, you may manage the children again. The XtUnmanageChild function 
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constructs a widget list of length one and calls XtUnmanageChildren. 

SEE ALSO 

XtMapWidget(3X), XtRealizeWidget(3X) 
Programming with Xlib 
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NAME 

XtMapWidget, XtSetMappedWhenManaged, XtUnmapWidget - map and unmap widgets 

SYNTAX 

XtMapWidget(>v) 
Widget w; 

void XtSetMappedWhenManaged(M>, mapjvhenjnanaged) 
Widget w; 

Boolean mapjvhenjnanaged; 
XtUnmapWidget(>v) 
Widget w; 

ARGUMENTS 

mapjvhenjnanaged 

Specifies a Boolean value that indicates the new value of the 
map_when_managed field. 

w Specifies the widget. 

DESCRIPTION 

If the widget is realized and managed and if the new value of map_when_managed is True, 
XtSetMappedWhenManaged maps the window. If the widget is realized and managed and if the 
new value of mapjvhenjnanaged is False, it unmaps the window. XtSetMappedWhenManaged 
is a convenience function that is equivalent to (but slightly faster than) calling XtSetValues and 
setting the new value for the mappedWhenManaged resource. As an alternative to using 
XtSetMappedWhenManaged to control mapping, a client may set mapped jvhen jnanaged to 
False and use XtMapWidget and XtUnmapWidget explicitly. 

SEE ALSO 

XtManageChildren(3X) 
Programming with Xlib 
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NAME 

XtNameToWidget, XtWidgetToWindow - translating strings to widgets or widgets to windows 

SYNTAX 

Widget XtNameToWidget(re/ere«ce, names); 

Widget reference; 

String names; 
Widget XtWindowToWidget(disp/qy, window) 

Display 'display; 

Window window; 

ARGUMENTS 
display 

names 

reference 

window 

DESCRIPTION 

The XtNameToWidget function looks for a widget whose name is the first component in the 
specified names and that is a pop-up child of reference (or a normal child if reference is a subclass 
of compositeWidgetClass). It then uses that widget as the new reference and repeats the search 
after deleting the first component from the specified names. If it cannot find the specified widget, 
XtNameToWidget returns NULL. Note that the names argument contains the name of a widget 
with respect to the specified reference widget and can contain more than one widget name 
(separated by periods) for widgets that are not direct children of the specified reference widget. If 
more than one child of the reference widget matches the name, XtNameToWidget can return any 
of the children. The X Toolkit Intrinsics do not require that all children of a widget have unique 
names. If the specified names contain more than one component and if more than one child 
matches the first component, XtNameToWidget can return NULL if the single branch that it 
follows does not contain the named widget. That is, XtNameToWidget does not back up and 
follow other matching branches of the widget tree. The XtWindowToWidget function translates 
the specified window and display pointer into the appropriate widget instance. 

SEE ALSO 

Programming with Xlib 



Specifies the display on which the window is defined. 
Specifies the fully qualified name of the desired widget. 
Specifies the widget from which the search is to start. 
Specify the window for which you want the widget. 
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NAME 

XtOffset, XtNumber - determine the byte offset or number of array elements 

SYNTAX 

Cardinal XtOKsct(pointerjype, field jiame) 

Type pointer jype; 

Field field jiame; 
Cardinal XtNumber(amzy) 

ArrayVariable array; 

ARGUMENTS 

array Specifies a fixed-size array. 

field jiame Specifies the name of the field for which to calculate the byte offset. 

pointer jype Specifies a type that is declared as a pointer to the structure. 

DESCRIPTION 

The XtOffset macro is usually used to determine the offset of various resource fields from the 
beginning of a widget and can be used at compile time in static initializations. The XtNumber 
macro returns the number of elements in the specified argument lists, resources lists, and other 
counted arrays. 

SEE ALSO 

XtGetResourceList(3X), XtSetArg(3X) 
Programming with Xlib 
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NAME 

XtOwnSelection, XtDisownSelection - set selection owner 

SYNTAX 

Boolean XtOwnSelection^, selection, time, convert jproc, lose jelection, done _proc) 
Widget w; 
Atom selection; 
Time time; 

XtConvertSelectionProc convert _proc; 
XtLoseSelectionProc lose jelection; 
XtSelectionDoneProc done _proc; 
void XtDisownSelection(n>, selection, time) 
Widget w; 
Atom selection; 
Time time; 

ARGUMENTS 

cancel _callback Specifies the callback procedure. 

client jdata Specifies the argument that is to be passed to the appropriate procedure 

when one of the condition occurs. 

convert _proc Specifies the procedure that is to be called whenever someone requests the 

current value of the selection. 

done _proc Specifies the procedure that is called after the requestor has received the 

selection or NULL if the owner is not interested in being called back. 

lose jelection Specifies the procedure that is to be called whenever the widget has lost 

selection ownership or NULL if the owner is not interested in being called 
back. 

selection Specifies an atom that describes the type of the selection (for example, 

XA PRIMARY, XASECONDARY, or XACLIPBOARD). 

time Specifies the timestamp that indicates when the selection ownership should 

commence or is to be relinquished. 

w Specifies the widget that wishes to become the owner or to relinquish 

ownership. 

DESCRIPTION 

The XtOwnSelection function informs the X Toolkit Intrinsics selection mechanism that a widget 
believes it owns a selection. It returns True if the widget has successfully become the owner and 
False otherwise. The widget may fail to become the owner if some other widget has asserted 
ownership at a time later than this widget. Note that widgets can lose selection ownership either 
because someone else asserted later ownership of the selection or because the widget voluntarily 
gave up ownership of the selection. Also note that the lose_selection procedure is not called if the 
widget fails to obtain selection ownership in the first place. The XtOwnSelectionlncremental 
informs the X Toolkit Intrinsics incremental selection mechanism that the specified widget 
believes it owns the selection. It returns True if the specified widget successfully becomes the 
selection owner or False otherwise. Widgets that use the incremental transfer mechanism should 
use XtDisownSelection to relinquish selection ownership. The XtDisownSelection function 
informs the X Toolkit Intrinsics selection mechanism that the specified widget is to lose 
ownership of the selection. If the widget does not currently own the selection either because it lost 
the selection or because it never had the selection to begin with, XtDisownSelection does nothing. 
After a widget has called XtDisownSelection, its convert procedure is not called even if a request 
arrives later with a timestamp during the period that this widget owned the selection. However, its 
done procedure will be called if a conversion that started before the call to XtDisownSelection 
finishes after the call to XtDisownSelection. 

SEE ALSO 

XtAppGetSelectionTimeout(3X), XtGetSelectionValue(3X) 
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Series 300 and 800 Only 



XtPar seAcceleratorTable (3X) 



NAME 

XtParseAcceleratoiTable, XtlnstallAccelerators, XtlnstallAllAccelerators - managing accelerator 
tables 

SYNTAX 

XtAccelerators XtParseAcceleratoiTable(sowrce) 

String source; 
void XtInstallAccelerators(rfeyrt'/rarion, source) 

Widget destination; 

Widget source; 
void XtInstallAllAccelerators(rfe««a//o/i, source) 

Widget destination; 

Widget source; 

ARGUMENTS 

source Specifies the accelerator table to compile. 

destination Specifies the widget on which the accelerators are to be installed. 

source Specifies the widget or the root widget of the widget tree from which the 

accelerators are to come. 

DESCRIPTION 

The XtParseAcceleratoiTable function compiles the accelerator table into the opaque internal 
representation. The XtlnstallAccelerators function installs the accelerators from source onto 
destination by augmenting the destination translations with the source accelerators. If the source 
display accelerator method is non-NULL, XtlnstallAccelerators calls it with the source widget 
and a string representation of the accelerator table, which indicates that its accelerators have been 
installed and that it should display them appropriately. The string representation of the 
accelerator table is its canonical translation table representation. The XtlnstallAllAccelerators 
function recursively descends the widget tree rooted at source and installs the accelerators of each 
widget encountered onto destination. A common use os to call XtlnstallAllAccelerators and pass 
the application main window as the source. 

SEE ALSO 

XtParseTranslationTable(3X) 
Programming with Xlib 



Hewlett-Packard Company 



-1- 



Jul 16, 1989 



XtWidgetCallCallbacks (3X) 



Series 300 and 800 Only 



XtWidgetCallCallbacks (3X) 



NAME 

XtWidgetCallCallbacks - a function that invokes the entries on a callback list. 

SYNTAX 

#include <Xm/Xm.h> 

void XtWidgetCallCallbacks (callbacks, call data) 



DESCRIPTION 

XtWidgetCallCallbacks calls the entries on a callback list. The widget knows the address of the 
callback list and avoids extra processing by using this function. The external version of this 
routine is XtCallCallbacks. 

ARGUMENTS 

callbacks Specifies the callback list to execute. 

call _data Specifies a callback-list specific data value to pass to each of the callback 



XtCallbackList 
Opaque 



callbacks; 
call data; 



procedures in the list. 
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XtWidgetHasCallbacks (3X) 



Series 300 and 800 Only 



XtWidgetHasCallbacks (3X) 



NAME 

XtWidgetHasCallbacks - a function that finds out the status of a callback list. 

SYNTAX 

#include <Xm/Xm.h> 

XtCallbackStatus XtWidgetHasCallbacks (callbacks) 
XtCallbackList callbacks', 

DESCRIPTION 

XtWidgetHasCallbacks returns the status of the specified callback list. The external version of 
this routine is XtHasCallbacks. 

callbacks Specifies the callback list to execute. 

call _data Specifies a callback-list specific data value to pass to each of the callback 
procedures in the list. 

RETURN VALUE 

Returns XtCallbackNoList if no callback list; XtCallbackHasNone if the callback list is empty, or 
XtCallbackHasSome if the callback list has at least one callback registered. 
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Above, 6-4, 6-5 
Accelerator, Defined, 10-7 
accept_focus procedure, 7-7 
Action Table, 10-2 

Action_proc procedure, Defined, 10-1 
Application, 4-10 
Application context, Defined, 2-2 
Application programmer, Defined, 1-2 
ApplicationShell, 4-1, 4-2 
ApplicationShellWidget, 4-4, 9-5 
applicationShellWidgetClass, 4-4 
ArgList, 1-13, 2-10, 2-11 
Defined, 2-10 

B 

Background, 9-2 
Below, 6-4, 6-5 
Bottomlf, 6-4, 6-5 

ButtonPress, 5-6, 7-4, 7-10, B-2, B-5, B-7, 
B-8 

ButtonRelease, 7-4, 7-10, B-2, B-5, B-7, 
B-8 



calloc, 11-2 
CenterGravity, 2-19 
Chaining, 2-14, 2-15, 9-6 

Subclass, 1-21 

superclass, 1-21 
change_managed procedure, 3-4 
CirculateNotify, B-5, B-8 
CirculateRequest, B-5, B-8 
Class, Defined, 1-2 
Class Initialization, 1-22 



Class_initialize procedure, Defined, 1-22 
Class_name, Defined, 1-17 
Client, Defined, 1-2 

ClientMessage, 7-16, 7-17, 7-18, B-5, B-8 
ColormapNotify, B-5, B-8 
Composite, 1-9, 1-10, 1-11, 1-23, 1-24, 

1- 25, 2-1, 3-2, 4-2, 5-1, 6-1, 6-2, 7-6, 
9-9 

Defined, 1-9 
Composite widgets, 2-1 
CompositeClassPart, 1-9 

Defined, 1-10 
CompositeClassR.ee, 1-10 
CompositePart, 1-9, 1-10, 1-12 

Defined, 1-10 
CompositeWidget, 1-10 

Defined, 1-11 
compositeWidgetClass, 1-10, 2-1, 2-12, 

2- 17 

CompositeWidgetClass, 2-18 
compositeWidgetClass, 2-19, 2-23, 2-24, 

3- 2, 3-4, 3-6, 3-8, 4-2, 6-3, 11-2 
CompositeWidgetClass, Defined, 1-10 
compress_enterleave, 7-13 
compress_expose field, 7-13 
compress_motion, 7-13 

Configure Window, 5-1 
ConfigureNotify, 2-21, 3-2, B-5, B-8 
ConfigureRequest, B-5, B-8 
ConstrainP.h, 1-17 

Constraint, 1-11, 1-12, 1-15, 1-17, 1-22, 3-2, 

3-8, 3-9, 9-9 
Defined, 1-11 
ConstraintClassPart, 1-11, 1-22, 2-16, 2-24, 

3-9 

Defined, 1-11 
ConstraintClassRec, 1-12 
Constraint.!!, 1-15 
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ConstraintPart, 1-11, 1-12, 9-20 

Defined, 1-12 
ConstraintWidget, 1-12 

Defined, 1-12 
constraintWidgetClass, 1-12, 2-12 
ConstraintWidgetClass, 2-18 
constraintWidgetClass, 2-23, 2-24, 3-9, 

9- 16, 9-17 
ConstraintWidgetClass, Defined, 1-11 
CopyFromParent, 2-18, 2-19 

Core, 1-6, 1-8, 1-9, 1-10, 1-12, 1-22, 1-23, 

1- 24, 1-25, 2-12, 2-17, 2-18, 2-19, 

2- 20, 3-5, 7-15, 9-6, 9-9, 9-17, 9-20 
Defined, 1-6 

CoreClass, 10-4 
CoreClassPart, 1-6, 2-24 

Defined, 1-6 
CorePart, 1-6, 1-7, 1-10, 5-1 

Defined, 1-7 
CreateNotify, B-5, B-8 
CurrentTime, 11-10, 11-11 
CWBorderWidth, 6-4 
CWHeight, 6-4 
CWSibling, 6-4 
CWStackMode, 6-4, 6-11 
CWWidth, 6-4 
CWX, 6-4 
CWY, 6-4 

D 

delete_child procedure, 3-4 
Destroy Callbacks, 2-23, 7-1 
Destroy procedure, Defined, 2-24 
DestroyNotify, B-5, B-8 
Display, 2-2 

display_accelerator, B-7 
Display_accelerator procedure, Defined, 

10- 7 



E 

EastGravity, 2-19 

EnterNotify, 7-4, 7-10, B-2, B-5, B-8, B-10, 

B-ll 
EnterWindow, 5-6 
Events, 7-7 
exit, 2-25 

Expose, 2-19, 7-13, 7-15, 9-19, 11-12, 

11-13, B-5, B-8 
expose procedure, 7-14 

F 

False, 1-8, 1-23, 2-17, 3-1, 3-7, 3-8, 4-7, 4-8, 
4-9, 5-4, 5-6, 5-7, 7-5, 7-7, 7-10, 7-11, 
7-14, 7-15, 11-8, 11-11 

Focusln, 7-6, 7-7, 7-10, B-5, B-8 

FocusNotify, 7-6 

FocusOut, 7-6, 7-7, 7-10, B-5, B-8 
fonts.alias, 9-2 
Foreground, 9-2 
free, 11-2 

G 

Geometry Management, 5-1 
geometryjtnanager field, 5-1 
Get_values_hook procedure, Defined, 
9-16 

Grabbing Input, 7-4 

GraphicsExpose, 7-16, 7-17, 7-18, 11-12, 

11-13, B-5 
GraphicsExpose,, B-8 
GravityNotify, B-5, B-8 

H 

hook, 9-16, 9-17 
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I 



N 



Inheritance, 1-21, 2-14, 2-15, 2-18, 9-6 
Initialization, 1-22, 2-14, 2-15, 2-16 
initialize procedure, 2-15 
Initialize procedure, Defined, 2-14 
Initialize_hook procedure, Defined, 2-16 
Input Grabbing, 7-4 
InputOnly, 2-19 
InputOutput, 2-19 

insert_child procedure, 1-25, 3-2, 5-2, C-l 
Insert_child procedure, Defined, 3-2 
Instance, Defined, 1-2 

K 

key modifier, B-4 

KeymapNotify, B-5, B-8 

KeyPress, 7-4, 7-6, 7-10, B-2, B-5, B-7, B-8 

KeyRelease, 7-4, 7-6, 7-10, B-2, B-5, B-8 

L 

LeaveNotify, 7-4, 7-10, B-2, B-5, B-8 
libXta, 1-5 

M 

malloc, 11-2 
MapNotify, B-5, B-8 
MappingNotify, 7-16, 7-17, 7-18, B-5 
MapRequest, B-5, B-8 
MenuPopdown, 5-7, 5-8, 10-3, C-7 

Defined, 5-8 
MenuPopup, 5-4, 5-6, 5-7, 10-3, C-7 

Defined, 5-6 
Method, Defined, 1-3 
MotionNotify, 7-4, 7-10, B-2, B-5, B-7, B-8 



Name, Defined, 1-3 

NoExpose, 7-16, 7-17, 7-18, B-5, B-8 

None, 7-6 

NorthWestGravity, 2-18, 7-14 

o 

Object, Defined, 1-3 
Opposite, 6-4, 6-5 
OverrideShell, 4-1, 4-2, 4-7 
OverrideShellWidget, 4-4 
overrideShellWidgetClass, 4-4 
OverrrideShell, 4-2 

P 

pop-up 

child, 5-1, 5-2 
Pop-up, Defined, 5-1 
pop-up, list, 5-1 

shell, 5-2 
printf, 11-15 

PropertyNotify, B-5, B-8 

Q 

query_geometry procedure, 6-11 
Query_geometry procedure, Defined, 6-10 

R 

realize procedure, 2-19 
realloc, 11-2 

ReparentNotify, B-5, B-8 
Resize procedure, Defined, 6-11 
ResizeRequest, B-5, B-8 
Resource, Defined, 1-3 
Resource Management, 9-1 
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SelectionClear, 7-16, 7-17, 7-18, B-5, B-8 
SelectionNotify, 7-16, 7-17, 7-18, B-5, B-8 
SelectionRequest, 7-16, 7-17, 7-18, B-5, 
B-8 

selectionTimeout, 11-6 
set_values procedure, 9-20 
Set_values procedure, Defined, 9-18 
Set_values_almost procedure, Defined, 
9-20 

set_values_hook procedure, 9-21 
Set_values_hook procedure, Defined, 9-21 
Shell, 2-1, 4-1, 4-2, 4-7, 5-2, 5-4, 5-6, 5-7, 
9-9 

Defined, 3-1 
ShellPart, Defined, 4-5 
SheUWidget, 4-4 

Defined, 4-6 
ShellWidgetClass, 4-4 
String, 2-14 
StringDefs.h, D-l 
Subclass Chaining, Defined, 1-21 
SubstructureNotify, 2-21 
Superclass, Defined, 1-17 
Superclass Chaining, 2-14, 2-15, 9-6 

Defined, 1-21 

T 

TARGETS, 11-8 
Toplf, 6-4, 6-5 
TopLevel, 4-9 
TopLevelShell, 4-1, 4-2 
TopLevelShellWidget, 4-4 
topLevelShellWidgetClass, 4-4, C-5 
TransientShell, 4-1, 4-2, 4-7, 4-8 
TransientShellWidget, 4-4 
transientShellWidgetClass, 4-4 
Translation Table, 10-4 
Translation tables, A-l 
True, 1-8, 1-20, 1-23, 2-4, 2-17, 2-18, 2-22, 
3-1, 3-5, 3-7, 3-8, 4-7, 4-8, 5-4, 5-6, 



6- 3, 7-5, 7-6, 7-10, 7-11, 7-12, 7-13, 

7- 15, 7-17, 9-18, 9-19, 11-8, 11-11 

u 

UnmapNotify, B-5, B-8 
User, Defined, 1-3 
/usr/lib/Xll/app-defaults/, 2-6 
/usr/lib/Xll/XtErrorDB, 11-14 

V 

VendorShell, 4-2 
VendorShellWidget, 4-4 
vendorShellWidgetClass, 4-4 
Version, Defined, 1-17 
Visibility, 7-15 

VisibilityNotify, 7-15, B-5, B-8 
Visible, 7-15 

w 

WestGravity, 2-19 
Widget, 1-7, 1-8 

Defined, 1-3, 1-8 
Widget class, Defined, 1-3 
Widget programmer, Defined, 1-3 
WidgetClass, 1-6, 1-7, 1-17 

Defined, 1-7 
Widget_class, Defined, 1-12 
WidgetClassRec, 1-7 
widgetClassRec, 1-17 
WidgetList, 3-5 
Widget_size, Defined, 1-17 
WMShell, 4-2, 4-8 
WMShellWidget, 4-4 
wmShellWidgetClass, 4-4 

X 

Xll/Convert.h, 9-12, C-5 
Xll/Intrinsich, 1-4, 1-5 
Xll/IntrinsicP.h, 1-5 
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Xll/keysymdef.h, B-7 
Xll/Label.h, 1-5 
Xll/Scroll.h, 1-5 
Xll/Shell.h, 1-4 
Xll/StringDefs.h, 1-4, 1-13, 9-1 
Xll/Xatoms.h, 1-4 
Xll/X.h, 6-4 
Xll/Xresource.h, 9-9 
Xll/Xutil.h, 11-13 
XACLIPBOARD, 11-11 
XAPRIMARY, 11-7, 11-11 
XASECONDARY, 11-7, 11-11 
XASTRING, 11-7, 11-9 
XClearArea, 9-18, 9-19 
XConfigureWindow, 2-21, 3-5, 6-3, 6-4, 

6-9, 6-10 
XCreateGC, 11-4, 11-5 
XCreateWindow, 2-18, 2-19 
.Xdefaults, 2-6 
.Xd&fauhs-host, 2-6 
XDestroyWindow, 2-22, 2-23 
XFreeGC, 2-24 
XFreePixmap, 2-24 
XMapWindow, 5-4, 5-7 
xmh, 2-8 

XMoveWindow, 3-5, 6-8 
XNextEvent, 7-7 
XOpenDisplay, 2-5, 2-6, 2-7 
XPeekEvent, 7-7 
XPending, 7-7 
XRInt, 9-9 

XrmOptionDescRec, Defined, 2-7 
XrmParseCommand, 2-3, 2-4, 2-7, 2-8, C-2 
XrmValue, 9-4, 9-9, 9-10 
XSelectlnput, 7-16, 7-17, 7-18 
XSetlnputFocus, 7-6, 7-7 
XSetWindowAttributes, 2-17, 2-18, 7-19 
XSynchronize, 2-4 
XtAcceptFocusProc, 7-7 

Defined, 7-7 
XtActionList, 10-2 
XtActionProc, 10-1 

Defined, 10-1 



XtActionsRec, 10-2 
XtAddActions, 10-3, C-7 

Defined, C-7 
XtAddCallback, 2-23, 8-2 

Defined, 8-2 
XtAddCallbacks, 8-3 

Defined, 8-3 
XtAddConverter, C-5 

Defined, C-5 
XtAddEventHandler, 2-24, 7-8, 7-16, 7-17, 
7-18, 7-19 

Defined, 7-16 
XtAddExposureToRegion, 11-12, 11-13 

Defined, 11-12 
XtAddGrab, 7-4, 7-5, 7-10 

Defined, 7-5 
XtAddlnput, C-l, C-4 

Defined, C-3 
XtAddRawEventHandler, 7-17, 7-18 

Defined, 7-17 
XtAddress, 9-13, C-6 
XtAddressMode, 9-12, C-5 
XtAddTimeOut, C-l, C-4 

Defined, C-4 
XtAddWorkProc, C-l 

Defined, C-4 
XtAllEvents, 7-17 
XtAlmostProc, 9-20 

Defined, 9-20 
XtAppAddActions, 10-2 

Defined, 10-2 
XtAppAddConverter, 9-12 

Defined, 9-12 
XtAppAddlnput, 7-2, 7-3, C-4 

Defined, 7-2 
XtAppAddTimeOut, 2-24, 7-3, 7-4, C-4 

Defined, 7-3 
XtAppAddWorkProc, 7-12, C-4 

Defined, 7-12 
XtAppContext, 2-2 

Defined, 2-2 
XtAppCreateShell, 1-1, 2-1, 2-2, 2-12, 
2-13, 9-5, C-2, C-5 
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Defined, 2-13 
XtAppError, 11-18 

Defined, 11-18 
XtAppErrorMsg, 11-16, 11-18 

Defined, 11-16 
XtAppGetErrorDatabase, 11-14 

Defined, 11-14 
XtAppGetErrorDatabaseText, 11-15, 
11-16 

Defined, 11-15 
XtAppGetErrorDatbaseText, 11-14 
XtAppGetSelectionTimeout, 11-6 

Defined, 11-6 
XtAppMainLoop, 7-1, 7-9, 7-10, C-2 

Defined, 7-10 
XtAppNextEvent, 7-8, 7-10, 7-11, C-2 

Defined, 7-8 
XtAppPeekEvent, 7-8, C-3 

Defined, 7-8 
XtAppPending, 7-7, 7-8, C-3 

Defined, 7-7 
XtAppProcessEvent, 7-8, 7-9, 7-11, C-3 

Defined, 7-9 
XtAppSetErrorHandler, 11-18 

Defined, 11-18 
XtAppSetErrorMsgHandler, 11-16 

Defined, 11-16 
XtAppSetSelectionTimeout, 11-6 

Defined, 11-6 
XtAppSetWarningHandler, 11-18 

Defined, 11-18 
XtAppSetWarningMsgHandler, 11-17 

Defined, 11-17 
XtAppWarning, 11-19 

Defined, 11-19 
XtAppWarningMsg, 11-17, 11-19 

Defined, 11-17 
XtArgsFunc, 9-21 

Defined, 9-21 
XtArgsProc, 2-16, 9-16 

Defined, 2-16 
XtArgVal, 2-10 

XtAugmentTranslations, 10-5, 10-6 



Defined, 10-6 
XtBaseOffiset, 9-13, C-6 
XtBuildEventMask, 7-19 

Defined, 7-19 
XtButtonBoxAddButton, C-l 
XtButtonBoxDeleteButton, C-l 
XtC, 1-13, 9-2 
XtCallAcceptFocus, 7-7 

Defined, 7-7 
XtCallbackExclusive, 5-4, 5-5, 5-7 

Defined, 5-5 
XtCallbackHasNone, 8-5 
XtCallbackHasSome, 8-5 
XtCallbackList, 8-1, 8-2 

Defined, 8-2 
XtCallbackNoList, 8-5 
XtCallbackNone, 5-4, 5-5, 5-7 

Defined, 5-5 
XtCallbackNonexclusive, 5-4, 5-5, 5-7 

Defined, 5-5 
XtCallbackPopdown, 5-7, 5-8 

Defined, 5-7 
XtCallbackProc, 2-23, 8-1 

Defined, 8-1 
XtCallbackRec, Defined, 8-2 
XtCallCallbacks, 8-3, 8-4 

Defined, 8-4 
XtCalloc, 2-24, 11-2, 11-3 

Defined, 11-3 
XtCaseProc, 10-10, 10-11 

Defined, 10-10 
XtCheckSubclass, 1-20, 1-21, 5-4, 5-6, 5-7 

Defined, 1-20 
XtClass, 1-19, 1-20 

Defined, 1-19 
XtCloseDisplay, 2-5 

Defined, 2-5 
XtConfigureWidget, 6-1, 6-8, 6-9 

Defined, 6-9 
XtConvert, 9-14, 9-15 

Defined, 9-14 
XtConvertArgRec, 9-12, C-5 
XtConvertCase, 10-11 
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Defined, 10-11 
XtConverter, 9-10 

Defined, 9-10 
XTCONVERTFAIL, 11-9 
XtConvertSelectionProc, 11-8 

Defined, 11-7 
XtCreateApplicationContext, 2-2, C-2 

Defined, 2-2 
XtCreateApplicationShell, C-l, C-5 

Defined, C-4 
XtCreateLabel, C-l 

XtCreateManagedWidget, 2-12, 3-1, 3-5, 
3-6 

Defined, 3-5 
XtCreatePopupShell, 2-13, 5-2 

Defined, 5-2 
XtCreateWidget, 1-8, 1-23, 2-9, 2-11, 2-12, 
2-17, 3-1, 3-2, 3-4, 3-5, 3-6, 3-9, 8-1, 

8- 2, 9-1, 9-6, 9-16, 9-22, B-l 
Defined, 2-11 

XtCreateWindow, 2-18, 2-19, 2-21 

Defined, 2-19 
XtCWQueryOnly, 6-3, 6-4, 6-5, 6-6, 6-7, 
6-8 

XtDatabase, 2-6, 2-7 

Defined, 2-6 
XtDefaultBackground, 1-8, 2-4, 2-8, 9-9, 

9- 11 

XtDefaultFont, 9-9, 9-11 
XtDefaultForeground, 1-8, 2-4, 2-8, 9-3, 
9-9, 9-11 

XtDestroyApplicationContext, 2-2, 2-3, 

2- 5, 2-25 
Defined, 2-2 

XtDestroyGC, 2-24, C-6, C-7 

Defined, C-6 
XtDestroyWidget, 2-1, 2-17, 2-22, 2-24, 

3- 1, 3-4, 3-10, 5-1 
Defined, 2-22 

XtDirectConvert, 9-14, 9-15 

Defined, 9-14 
XtDisownSelection, 11-12 

Defined, 11-12 



XtDispatchEvent, 2-22, 7-5, 7-6, 7-9, 7-10, 
C-2 

Defined, 7-9 
XtDisplay, 2-20 

Defined, 2-20 
XtDisplaylnitialize, 2-2, 2-3, 2-4, 2-5, 2-6, 
2-7, 2-8, 2-13, C-2 

Defined, 2-3 
XtError, 11-16 
_XtError, 11-18 
XtError, C-9, C-10 

Defined, C-10 
XtErrorHandler, 11-17 

Defined, 11-17 
XtErrorMsg, 1-21, 11-3, 11-4, C-9, C-10 

Defined, C-9 
XtErrorMsgHandler, 11-14 

Defined, 11-14 
XtEventHandler, 7-15 

Defined, 7-15 
XtExposeProc, 7-14 

Defined, 7-14 
XtFree, 2-11, 2-24, 9-5, 11-2, 11-3, 11-4, 
11-7, 11-9 

Defined, 11-3 
XtGeometryAlmost, 6-3, 6-5, 6-6, 6-7, 

6-11, 9-18, 9-20 
XtGeometryDone, 6-3, 6-7 
XtGeometryHandler, 6-6, 6-10 

Defined, 6-6 
XtGeometryMask, 6-4 
XtGeometryNo, 4-8, 6-3, 6-7, 6-11, 9-18 
XtGeometryResult, 6-3 
XtGeometryYes, 6-2, 6-3, 6-7, 6-8, 6-11, 
9-18 

XtGetApplicationResources, 9-7, 9-8, 9-14 

Defined, 9-7 
XtGetErrorDatabase, C-8 

Defined, C-8 
XtGetErrorDatabaseText, C-8 

Defined, C-8 
XtGetErrorDatbaseText, C-8 
XtGetGC, 2-24, 11-5 
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Defined, 11-5 
XtGetResourceList, 9-5 

Defined, 9-5 
XtGetSelectionTimeout, C-7 

Defined, C-7 
XtGetSelectionValue, 11-9, 11-10 

Defined, 11-9 
XtGetSelectionValues, 11-9, 11-10 

Defined, 11-10 
XtGetSubresources, 9-7, 9-14 

Defined, 9-7 
XtGetSubvalues, 9-16, 9-17 

Defined, 9-16 
XtGetValues, 3-10, 8-1, 8-2, 9-5, 9-15, 9-16 

Defbed, 9-15 
XtGrabExclusive, 5-4, 5-5, 5-6, 5-7 
XtGrabKind, 5-4 
XtGrabNone, 5-5 

XtGrabNonexclusive, 5-4, 5-5, 5-6, 5-7 
XtHasCallbacks, 8-5 

Defined, 8-5 
XtlMAU, 7-9 

XtlMAlternatelnput, 7-8, 7-9 
Xtlmmediate, 9-13, C-6 
XtlMTimer, 7-8, 7-9 
XtlMXEvent, 7-8, 7-9 
Xtlnherit, 1-24 
XtlnheritAcceptFocus, 1-25 
XtlnheritChangeManaged, 1-25 
XtlnheritDeleteChild, 1-25 
XtlnheritDisplayAccelerator, 1-25 
XtlnheritExpose, 1-25 
XtlnheritGeometryManager, 1-25 
XtlnheritlnsertChild, 1-25 
XtlnheritRealize, 1-25 
XtlnheritResize, 1-25 
XtlnheritSetValuesAlmost, 1-25, 9-20 
XtlnheritTranslations, 10-4 
Xtlnitialize, C-l, C-2, C-3, C-4, C-5 

Defined, C-l 
XtlnitProc, 2-14, 2-15 

Defined, 2-14 
XtlnputCallbackProc, 7-2 



Defined, 7-2 
XtlnputExceptMask, 7-2 
XtlnputReadMask, 7-2 
XtlnputWriteMask, 7-2 
XtlnstallAccelerators, 10-8 

Defined, 10-8 
XtlnstallAllAccelerators, 10-8, 10-9 

Defined, 10-8 
XtlsComposite, 3-2 

Defined, 3-2 
XtlsManaged, 3-7 

Defined, 3-7 
XtlsRealized, 2-17 

Defined, 2-17 
XtlsSensitive, 7-11 

Defined, 7-11 
XtlsSubclass, 1-20, 3-2 

Defined, 1-20 
XtKeyProc, 10-9, 10-11, B-4 

Defined, 10-9 
XtLabelCreate, B-l 
XtLoseSelectionProc, Defined, 11-8 
XtMainLoop, C-l, C-2 

Defined, C-2 
XtMakeGeometryRequest, 2-1, 6-1, 6-2, 
6-3, 6-4,6-5, 6-7, 6-12 

Defined, 6-2 
XtMakeResizeRequest, 6-1, 6-5, 6-12 

Defined, 6-5 
XtMalloc, 2-24, 11-2, 11-3, 11-4 

Defined, 11-3 
XtManageChild, 1-25, 2-9, 3-1, 3-5, 3-6, 
C-l 

Defined, 3-5 
XtManageChildren, 2-17, 3-1, 3-4, 3-5, C-l 

Defined, 3-4 
XtMapWidget, 3-8 

Defined, 3-8 
XtMergeArgLists, 2-11 

Defined, 2-11 
XtMoveWidget, 3-5, 6-1, 6-8 

Defined, 6-8 
XtN, 1-13, 9-1 
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XtNameToWidget, 11-1, 11-2 

Defined, 11-1 
XtNew, 11-4 

Defined, 11-4 
XtNewString, 11-4 

Defined, 11-4 
XtNextEvent, C-l, C-2 

Defined, C-2 
XtNumber, 2-10, 2-12, 11-1 

Defined, 11-1 
XtOffset, 9-3, 9-6 

Defined, 9-6 
XtOpenDisplay, 2-2, 2-4, 2-5, 2-7, C-2 

Defined, 2-4 
XtOrderProc, 3-3 

Defined, 3-3 
XtOverrideTranslations, 10-5, 10-6 

Defined, 10-6 
XtOwnSelection, 11-11 

Defined, 11-11 
XtParent, 2-20 

Defined, 2-20 
XtParseAcceleratorTable, 10-8 

Defined, 10-8 
XtParseTranslationTable, 10-4, 10-5 

Defined, 10-5 
XtPeekEvent, C-l, C-3 

Defined, C-3 
XtPending, C-l, C-3 

Defined, C-3 
XtPopdown, 4-8, 5-7, 5-8 

Defined, 5-7 
XtPopdownID, 5-8 
XtPopup, 4-8, 5-4, 5-5, 5-7, 7-4 

Defined, 5-4 
XtProc, 1-22 

Defined, 1-22 
XtProcessEvent, C-l, C-3 

Defined, C-2 
XtQueryGeometry, 6-10, 6-11 

Defined, 6-10 
XtR, 1-14 

XtRAcceleratorTable, 9-3, 9-9 



XTranslateCoordinates, 11-13 
XtRBool, 9-3, 9-9 
XtRBoolean, 9-3, 9-9 
XtRCallback, 8-2, 9-3 
XtRCallProc, 9-4 
XtRColor, 9-3, 9-9 
XtRCursor, 9-3, 9-9 
XtRDimension, 9-3, 9-9 
XtRDisplay, 9-3, 9-9 
XtRealizeProc, 2-17 

Defined, 2-17 
XtRealizeWidget, 2-1, 2-9, 2-16, 2-17, 2-18 
2-19, 2-21, 3-5, 5-3, 5-4, 5-7, 7-14, 
7-19 

Defined, 2-16 
XtRealloc, 11-2, 11-3 

Defined, 11-3 
XtRegisterCaseConverter, 10-11 

Defined, 10-11 
XtReleaseGC, 11-5, C-7 

Defined, 11-5 
XtRemoveAUCallbacks, 8-4 

Defined, 8-4 
XtRemoveCallback, 2-23, 8-3, 8-4 

Defined, 8-3 
XtRemoveCallbacks, 8-4 

Defined, 8-4 
XtRemoveEventHandler, 2-24, 7-17 

Defined, 7-17 
XtRemoveGrab, 5-7, 7-4, 7-5, 7-6 

Defined, 7-5 
XtRemovelnput, 7-3 

Defined, 7-3 
XtRemoveRawEventHandler, 7-18 

Defined, 7-18 
XtRemoveTimeOut, 2-24, 7-4 

Defined, 7-4 
XtRemoveWorkProc, 7-12, 7-13 

Defined, 7-12 
XtResizeWidget, 3-5, 6-1, 6-8, 6-9, 6-10, 
6-11 

Defined, 6-8 
XtResizeWindow, 6-9, 6-10 
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Defined, 6-9 
XtResource, 9-1 
XtResourceDefaultProc, 9-4 
XtResourceList, 1-12, 9-1 
XtResourceQuark, 9-13, C-6 
XtResourceString, 9-13, C-6 
XtRFile, 9-3, 9-9 
XtRFloat, 9-3, 9-9 
XtRFont, 9-3, 9-9 
XtRFontStruct, 9-3, 9-9 
XtRFunction, 9-3 
XtRImmediate, 9-4 
XtRInt, 9-3, 9-9 
XtRPixel, 9-3, 9-9 
XtRPixmap, 9-3, 9-9 
XtRPointer, 9-3 
XtRPosition, 9-3, 9-9 
XtRShort, 9-3, 9-9 
XtRString, 9-3, 9-9 
XtRTranslationTable, 9-3, 9-9 
XtRUnsignedChar, 9-3, 9-9 
XtRWidget, 9-3 
XtRWindow, 9-3 
XtScreen, 2-21 

Defined, 2-20 
XtSelectionCallbackProc, Defined, 11-8 
XtSelectionDoneProc, 11-7, 11-8 

Defined, 11-8 
XtSetArg, 2-10, 2-11 

Defined, 2-10 
XtSetErrorHandler, C-10 

Defined, C-10 
XtSetErrorMsgHandler, C-8 

Defined, C-8 
XtSetKeyboardFocus, 7-6 

Defined, 7-6 
XtSetKeyiranslator, 10-9 

Defined, 10-9 
XtSetMappedWhenManaged, 3-1, 3-7, 3-8 

Defined, 3-7 
XtSetSelectionTimeout, C-7 

Defined, C-7 
XtSetSensitive, 5-3, 5-5, 5-8, 7-11 



Defined, 7-11 
XtSetSubvalues, 9-21 

Defined, 9-21 
XtSetValues, 1-13, 2-21, 3-8, 3-10, 5-3, 6-1, 
6-2, 7-11, 8-1, 8-2, 9-5, 9-17, 9-18, 
9-19, 9-20, 9-21, 10-6 

Defined, 9-17 
XtSetValuesFunc, 9-18, 9-20 

Defined, 9-18 
XtSetWarningHandler, C-10 

Defined, C-10 
XtSetWarningMsgHandler, C-9 

Defined, C-9 
XtSMDontChange, 6-5, 6-11 
XtStringConversionWarning, 9-12 
XtStringProc, 10-7 

Defined, 10-7 
XtSuperclass, 1-20 

Defined, 1-20 
XtTimerCallbackProc, 7-3 

Defined, 7-3 
XtToolkitError, 11-17, C-l, C-9, C-10 
XtToolkitlnitialize, 2-2, C-2 

Defined, 2-2 
XtTranslateCoords, 11-13 

Defined, 11-13 
XtTranslateKey, 10-9 
XtTranslateKeycode, 10-10 

Defined, 10-10 
XtTranslations, 10-5 
XtUninstallTranslations, 10-7 

Defined, 10-7 
XtUnmanageChild, 2-23, 3-1, 3-7 

Defined, 3-7 
XtUnmanageChildren, 2-17, 3-1, 3-6, 3-7, 
C-l 

Defined, 3-6 
XtUnmapWidget, 2-25, 3-8 

Defined, 3-8 
XtUnrealizeWidget, 2-21 

Defined, 2-21 
XtVersion, 1-17 
XtVersionDontCheck, 1-17 
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XtWarning, 11-17 
XtWarning, 11-19 
XtWarning, C-9 
XtWarning, C-ll 
XtWarning, Defined, C-ll 
XtWarningMsg, 9-10, C-9, C-ll 

Defined, C-9 
XtWidgetClassProc, 1-23 

Defined, 1-23 
XtWidgetGeometry, 6-3, 6-4, 6-5, 6-10 
XtWidgetProc, 2-24, 3-2, 3-4, 6-11 

Defined, 2-24 
XtWidgetToApplicationContext, 2-3 

Defined, 2-3 
XtWindow, 2-21 

Defined, 2-21 
XtWindoWToWidget, 11-13 

Defined, 11-13 
XtWorkProc, 7-11 

Defined, 7-11 
XtWorkProcId, 7-12 
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